Skip to content

Commit a5d77f5

Browse files
markolbertmarkolbert
committed
update docs
1 parent 93262cf commit a5d77f5

File tree

11 files changed

+1772
-133
lines changed

11 files changed

+1772
-133
lines changed

‎J4JMapWinLibrary/docs/assets/map-pin.png‎

5.71 KB
Loading

‎J4JMapWinLibrary/docs/changes.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# J4JMapLibrary: Change Log
2+
3+
|Version|Comments|
4+
|:-----:|--------|
5+
|0.8|Initial release|

‎J4JMapWinLibrary/docs/map-control.md‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# J4JMapWinLibrary: J4JMapControl
2+
3+
## Basic usage
4+
5+
- [Basic usage](#basic-usage)
6+
- Properties
7+
- [Projection properties](#projection-properties)
8+
- [Map region properties](#map-region-properties)
9+
- [Overlay control properties](#overlay-control-properties)
10+
- [Caching properties](#caching-properties)
11+
- [Miscellaneous proeprties](#miscellaneous-properties)
12+
13+
*The test project `WinAppTest`, also contained in this repository, is a working example of using `J4JMapControl`.*
14+
15+
`J4JMapControl` supports:
16+
17+
- clicking and dragging to move the center point horizontally/vertically.
18+
- rotating the map around a point by holding down the *control* key while clicking and dragging.
19+
- using the mouse wheel to change the scale of the map
20+
21+
Using the control involves two steps. First, you must add it to an XAML file and set at least some of its properties:
22+
23+
```xml
24+
<map:J4JMapControl x:Name="mapControl"
25+
Grid.Column="0" Grid.Row="0" Grid.ColumnSpan="3"
26+
MapProjection="BingMaps"
27+
MapScale="13"
28+
Heading="45"
29+
Center="37.5072N,122.2605W">
30+
```
31+
32+
Second, in the code behind you must set the control's `ProjectionFactory` property:
33+
34+
```csharp
35+
mapControl.ProjectionFactory = J4JDeusEx.ServiceProvider.GetService<ProjectionFactory>();
36+
37+
if( mapControl.ProjectionFactory == null )
38+
_logger?.LogCritical( "ProjectionFactory is not defined" );
39+
```
40+
41+
This example uses my `J4JDeuxEx` generalized view model locator, but you can create a `MapFactory` instance in other ways. Consult the [`J4JMapLibrary` documentation](https://github.com/markolbert/J4JMapControl/tree/main/J4JMapLibrary) for details.
42+
43+
You may also want to set the control's `LoggerFactory` property if you want logging to occur:
44+
45+
```csharp
46+
var loggerFactory = ( (App) Application.Current ).LoggerFactory;
47+
48+
mapControl.LoggerFactory = loggerFactory;
49+
```
50+
51+
Again, this example uses my `J4JDeuxEx` generalized view model locator, but you can create an `ILoggerFactory` instance in other ways.
52+
53+
[return to top](#basic-usage)
54+
55+
## Projection properties
56+
57+
There are two properties which define the mapping service the control uses:
58+
59+
|Property|Type|Comments|
60+
|--------|----|--------|
61+
|`MapProjection`|`string`|the name of the mapping projection to use|
62+
|`MapStyle`|`string`|the specific style of map projection to use (only applies to certain mapping services; **not yet implemented**)|
63+
64+
If the map projection name is not recognized by `MapFactory` the control's projection is undefined and no imagery will display.
65+
66+
[return to top](#basic-usage)
67+
68+
## Map region properties
69+
70+
The region displayed by the control is defined by three properties:
71+
72+
|Property|Type|Comments|
73+
|--------|----|--------|
74+
|`Center`|`string`|must be a parseable latitude/longitude string; see below|
75+
|`Heading`|`double`|can be any value, but is adjusted to be within the range 0 to 360|
76+
|`MapScale`|`double`|converted to an integer internally. The value is adjusted internally if it falls outside the projection's supported range.|
77+
78+
Latitude/longitude strings must be in the following format:
79+
80+
- latitude numeric value (`double`)
81+
- latitude direction (`char`; optional - valid values are **N** or **S**, case doesn't matter)
82+
- comma
83+
- longitude numeric value (`double`)
84+
- longitude direction (`char`; optional - valid values are **E** or **W**, case doesn't matter)
85+
86+
If the latitude direction component is not provided the parser assumes *positive* latitudes are *north* while *negative* latitudes are *south*. Similarly, if the longitude direction component is not provided the parser assumes *positive* longitudes are *east* while *negative* longitudes are *west*.
87+
88+
The map's heading can also be set by calling the `SetHeadingByText()` method, supplying one of the following compass rose directions: N, E, S, W, NE, SE, SW, NW, NNE, ENE, ESE, SSE, SSW, WSW, WNW, NNW. Any other values are ignored.
89+
90+
[return to top](#basic-usage)
91+
92+
## Overlay control properties
93+
94+
`J4JMapControl` can display two controls above the map imagery, a compass rose showing the map's heading, and a slider control which can be used to adjust the map's scale.
95+
96+
There are a variety of properties which can be used to fine-tune these controls:
97+
98+
|Property|Type|Comments|
99+
|--------|----|--------|
100+
|`ControlVisibility`|`bool`|`true` displays the overlay controls, `false` hides them|
101+
|`HorizontalControlAlignment`|`HorizontalAlignment`|controls where the compass rose and map scale control are displayed horizontally within the map control. Default is `Right`.|
102+
|`VerticalControlAlignment`|`VerticalAlignment`|controls where the compass rose and map scale control are displayed vertically within the map control. Default is `Top`.|
103+
|`CompassRoseImage`|`BitmapImage`|the image used for the compass rose. It should be square so that scaling does not distort it.|
104+
|`CompassRoseHeightWidth`|`double`|the height/width of the compass rose control.|
105+
|`ControlBackground`|`Color`|the color of the `Brush` used to fill the overlay controls' background. Default is ARGB(255, 128, 128, 128).|
106+
|`ControlBackgroundOpacity`|`double`|the opacity of the overlay controls' background. Valid values are 0 to 1.0.|
107+
|`ControlVerticalMargin`|`double`|controls the vertical spacing between the compass rose and the map scale slider controls|
108+
|`LargeMapScaleChange`|`double`|defines what constitutes a "large" map scale change for the map scale slider control|
109+
110+
[return to top](#basic-usage)
111+
112+
## Caching properties
113+
114+
Many, but not all, projections support caching the retrieved imagery. There are a variety of properties available to define how caching works:
115+
116+
|Property|Type|Default|Comments|
117+
|--------|----|-------|--------|
118+
|`UseMemoryCache`|`bool`|`true`|controls whether or not in-memory caching is used when possible|
119+
|`MemoryCacheEntries`|`int`|`DefaultMemoryCacheEntries`|defines how many entries the in-memory cache will retain before it begins purging expired ones|
120+
|`MemoryCacheRetention`|`string`|`string.Empty`|defines how long entries are retained in the in-memory cache. **Not yet implemented**|
121+
|`MemoryCacheSize`|`int`|`DefaultMemoryCacheSize`|defines the maximum size, in bytes, the in-memory cache can be before it begins purging expired entries|
122+
|`FileSystemCachePath`|`string`|`string.Empty`|sets the folder where the `FileSystemCache` stores its files. If undefined, empty or an invalid location file system caching is disabled.|
123+
|`FileSystemCacheEntries`|`int`|`DefaultFileSystemCacheEntries`|defines how many files the file system cache will retain before it begins purging expired ones|
124+
|`FileSystemCacheRetention`|`string`|`string.Empty`|defines how long entries are retained in the file system cache. **Not yet implemented**|
125+
|`FileSystemCacheSize`|`int`|`DefaultFileSystemCacheSize`|defines the maximum size, in bytes, the file system cache can store in files be before it begins purging expired entries|
126+
127+
[return to top](#basic-usage)
128+
129+
## Miscellaneous properties
130+
131+
|Property|Type|Comments|
132+
|--------|----|--------|
133+
|`Annotations`|`List<FrameworkElement>`|holds the FrameworkElements which are displayed above the map as annotations. See the [`MapPin` documentation](map-pin.md) for details.|
134+
|`ShowRotationHints`|`bool`|shows (`true`) or hides (`false`) hints showing how a map's heading is being changed while using click-and-drag to rotate it|
135+
|`MinMapScale`|`double`|sets the minimum map scale allowed. Values outside the range of what the projection supports are adjusted automatically.|
136+
|`MaxMapScale`|`double`|sets the maximum map scale allowed. Values outside the range of what the projection supports are adjusted automatically.|
137+
|`UpdateEventInterval`|`int`|sets the throttling window, in milliseconds, controlling how UI adjustments to map properties are processed, to reduce unnecessary processing and image retrieval. If the supplied value is less than 0 it is set to `DefaultUpdateEventInterval`|
138+
139+
[return to top](#basic-usage)

‎J4JMapWinLibrary/docs/map-pin.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# J4JMapWinLibrary: MapPin
2+
3+
## Basic Usage
4+
5+
- [Basic usage](#basic-usage)
6+
- [Formatting properties](#formatting-properties)
7+
8+
The `MapPin` control displays an image similar to this:
9+
10+
![map pin](assets/map-pin.png)
11+
12+
To locate it on the map control you use the following *annotation properties*:
13+
14+
|Property|Type|Default|Comments|
15+
|--------|----|-------|--------|
16+
|`Location.Center`|`string`|`null`|must be a parseable latitude/longitude string. See the discussion on [map region properties](map-control#map-region-properties) for details.|
17+
|`Location.Offset`|`string`|"0,0"|the horizontal and vertical offsets, in pixels, to apply to `MapPin` when it is positioned on the map control. See below for details.|
18+
19+
The `Location.Offset` property must be in the following format:
20+
21+
- horizontal offset numeric value (`float`)
22+
- a separating comma or space
23+
- vertical offset numeric value (`float`)
24+
25+
If the value doesn't match the format `Location.Offset` defaults to **0, 0**.
26+
27+
[return to top](#basic-usage)
28+
29+
## Formatting properties
30+
31+
There are several properties which control what the `MapPin` looks like:
32+
33+
|Property|Type|Default|Comments|
34+
|--------|----|-------|--------|
35+
|`ArcRadius`|`double`|15|the radius of the circle forming the top of the image. Values less than 0 default to 15.|
36+
|`TailLength`|`double`|30|the height of the triangle forming the bottom of the image. Values less than 0 default to 30|
37+
|`Fill`|`Brush`|a solid red brush||
38+
|`Stroke`|`Brush`|a transparent brush||
39+
|`StrokeThickness`|`double`|0|values less than 0 default to 0|
40+
41+
[return to top](#basic-usage)

‎J4JMapWinLibrary/docs/readme.md‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,15 @@
1-
More to come...
1+
# J4JMapWinLibrary
2+
3+
WinUI 3/WinApp controls for displaying maps from online mapping services, with optional annotations.
4+
5+
The library is built under NET 7, with nullability enabled.
6+
7+
The change log can be found [here](changes.md).
8+
9+
The library depends on a companion library, **J4JMapLibrary**. You can read the documentation for that library on its [GitHub repository](https://github.com/markolbert/J4JMapControl/tree/main/J4JMapLibrary).
10+
11+
Control documentation:
12+
13+
- [J4JMapControl](map-control.md)
14+
- [MapPin](map-pin.md)
15+
- [Adding annotations](annotations.md)

‎J4JMapWinLibrary/map-control/dep-props/controls.cs‎

Lines changed: 51 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -7,49 +7,28 @@ namespace J4JSoftware.J4JMapWinLibrary;
77

88
public sealed partial class J4JMapControl
99
{
10-
public static DependencyProperty CompassRoseImageProperty = DependencyProperty.Register( nameof( CompassRoseImage ),
11-
typeof( BitmapImage ),
12-
typeof( J4JMapControl ),
13-
new PropertyMetadata( GetDefaultCompassRoseImage() ) );
14-
15-
public DependencyProperty CompassRoseHeightWidthProperty = DependencyProperty.Register(
16-
nameof( CompassRoseHeightWidth ),
17-
typeof( double ),
18-
typeof( J4JMapControl ),
19-
new PropertyMetadata( 100D ) );
20-
21-
public DependencyProperty ControlBackgroundOpacityProperty = DependencyProperty.Register(
22-
nameof( ControlBackgroundOpacity ),
23-
typeof( double ),
24-
typeof( J4JMapControl ),
25-
new PropertyMetadata( 0.6 ) );
26-
27-
public DependencyProperty ControlBackgroundProperty = DependencyProperty.Register( nameof( ControlBackground ),
28-
typeof( Color ),
29-
typeof( J4JMapControl ),
30-
new PropertyMetadata( 0 ) );
31-
32-
public DependencyProperty ControlVerticalMarginProperty = DependencyProperty.Register(
33-
nameof( ControlVerticalMargin ),
34-
typeof( double ),
35-
typeof( J4JMapControl ),
36-
new PropertyMetadata( 5D ) );
37-
3810
public DependencyProperty ControlVisibilityProperty = DependencyProperty.Register( nameof( ControlVisibility ),
3911
typeof( bool ),
4012
typeof( J4JMapControl ),
4113
new PropertyMetadata( true ) );
4214

15+
public bool ControlVisibility
16+
{
17+
get => (bool)GetValue(ControlVisibilityProperty);
18+
set => SetValue(ControlVisibilityProperty, value);
19+
}
20+
4321
public DependencyProperty HorizontalControlAlignmentProperty = DependencyProperty.Register(
4422
nameof( HorizontalControlAlignment ),
4523
typeof( HorizontalAlignment ),
4624
typeof( J4JMapControl ),
4725
new PropertyMetadata( HorizontalAlignment.Right ) );
4826

49-
public DependencyProperty LargeMapScaleChangeProperty = DependencyProperty.Register( nameof( LargeMapScaleChange ),
50-
typeof( double ),
51-
typeof( J4JMapControl ),
52-
new PropertyMetadata( 0.6 ) );
27+
public HorizontalAlignment HorizontalControlAlignment
28+
{
29+
get => (HorizontalAlignment)GetValue(HorizontalControlAlignmentProperty);
30+
set => SetValue(HorizontalControlAlignmentProperty, value);
31+
}
5332

5433
public DependencyProperty VerticalControlAlignmentProperty = DependencyProperty.Register(
5534
nameof( VerticalControlAlignment ),
@@ -63,61 +42,82 @@ public VerticalAlignment VerticalControlAlignment
6342
set => SetValue( VerticalControlAlignmentProperty, value );
6443
}
6544

66-
public HorizontalAlignment HorizontalControlAlignment
67-
{
68-
get => (HorizontalAlignment) GetValue( HorizontalControlAlignmentProperty );
69-
set => SetValue( HorizontalControlAlignmentProperty, value );
70-
}
71-
72-
public bool ControlVisibility
73-
{
74-
get => (bool) GetValue( ControlVisibilityProperty );
75-
set => SetValue( ControlVisibilityProperty, value );
76-
}
45+
public static DependencyProperty CompassRoseImageProperty = DependencyProperty.Register(nameof(CompassRoseImage),
46+
typeof(BitmapImage),
47+
typeof(J4JMapControl),
48+
new PropertyMetadata(GetDefaultCompassRoseImage()));
7749

7850
public BitmapImage CompassRoseImage
7951
{
8052
get => (BitmapImage) GetValue( CompassRoseImageProperty );
8153
set => SetValue( CompassRoseImageProperty, value );
8254
}
8355

56+
public DependencyProperty CompassRoseHeightWidthProperty = DependencyProperty.Register(
57+
nameof(CompassRoseHeightWidth),
58+
typeof(double),
59+
typeof(J4JMapControl),
60+
new PropertyMetadata(100D));
61+
8462
public double CompassRoseHeightWidth
8563
{
8664
get => (double) GetValue( CompassRoseHeightWidthProperty );
8765
set => SetValue( CompassRoseHeightWidthProperty, value );
8866
}
8967

68+
public DependencyProperty ControlBackgroundProperty = DependencyProperty.Register( nameof( ControlBackground ),
69+
typeof( Color ),
70+
typeof( J4JMapControl ),
71+
new PropertyMetadata( Color.FromArgb( 255, 128, 128, 128 ) ) );
72+
9073
public Color ControlBackground
9174
{
9275
get => (Color) GetValue( ControlBackgroundProperty );
9376
set => SetValue( ControlBackgroundProperty, value );
9477
}
9578

79+
public DependencyProperty ControlBackgroundOpacityProperty = DependencyProperty.Register(
80+
nameof(ControlBackgroundOpacity),
81+
typeof(double),
82+
typeof(J4JMapControl),
83+
new PropertyMetadata(0.6));
84+
9685
public double ControlBackgroundOpacity
9786
{
9887
get => (double) GetValue( ControlBackgroundOpacityProperty );
9988
set => SetValue( ControlBackgroundOpacityProperty, value );
10089
}
10190

102-
public double LargeMapScaleChange
91+
public DependencyProperty ControlVerticalMarginProperty = DependencyProperty.Register(
92+
nameof(ControlVerticalMargin),
93+
typeof(double),
94+
typeof(J4JMapControl),
95+
new PropertyMetadata(5D));
96+
97+
public double ControlVerticalMargin
10398
{
104-
get => (double) GetValue( LargeMapScaleChangeProperty );
99+
get => (double)GetValue(ControlVerticalMarginProperty);
105100

106101
set
107102
{
108-
value = value <= 0 ? 1 : 0;
109-
SetValue( LargeMapScaleChangeProperty, value );
103+
SetValue(ControlVerticalMarginProperty, value);
104+
SetMapControlMargins(value);
110105
}
111106
}
112107

113-
public double ControlVerticalMargin
108+
public DependencyProperty LargeMapScaleChangeProperty = DependencyProperty.Register(nameof(LargeMapScaleChange),
109+
typeof(double),
110+
typeof(J4JMapControl),
111+
new PropertyMetadata(0.6));
112+
113+
public double LargeMapScaleChange
114114
{
115-
get => (double) GetValue( ControlVerticalMarginProperty );
115+
get => (double) GetValue( LargeMapScaleChangeProperty );
116116

117117
set
118118
{
119-
SetValue( ControlVerticalMarginProperty, value );
120-
SetMapControlMargins( value );
119+
value = value <= 0 ? 1 : 0;
120+
SetValue( LargeMapScaleChangeProperty, value );
121121
}
122122
}
123123

‎J4JMapWinLibrary/map-control/dep-props/minmax-scale.cs‎

Lines changed: 0 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -14,19 +14,6 @@ public sealed partial class J4JMapControl
1414
typeof( J4JMapControl ),
1515
new PropertyMetadata( 0.0 ) );
1616

17-
//private static void OnMinMaxScaleChanged( DependencyObject d, DependencyPropertyChangedEventArgs e )
18-
//{
19-
// if( d is not J4JMapControl mapControl )
20-
// return;
21-
22-
// if( mapControl.MapScale >= mapControl.MinScale && mapControl.MapScale <= mapControl.MaxScale )
23-
// return;
24-
25-
// mapControl.MapScale = mapControl.MapScale < mapControl.MinScale
26-
// ? mapControl.MinScale
27-
// : mapControl.MaxScale;
28-
//}
29-
3017
public double MinMapScale
3118
{
3219
get => (double) GetValue( MinMapScaleProperty );

0 commit comments

Comments
 (0)