This repository has been archived by the owner on Aug 8, 2023. It is now read-only.
Add back MGLStyleFunction and re-document MGLStyleValue #7943
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -30,9 +30,10 @@ typedef NS_ENUM(NSUInteger, MGLInterpolationMode) { | |
|
|
||
| The `MGLStyleValue` class itself represents a class cluster. Under the hood, a | ||
| particular `MGLStyleValue` object may be either an `MGLStyleConstantValue` to | ||
| represent a constant value or one of the concrete subclasses of | ||
| `MGLStyleFunction` to represent a value function. Do not initialize an | ||
| `MGLStyleValue` object directly; instead, use one of the class factory methods | ||
| to create an `MGLStyleValue` object. | ||
|
|
||
| The `MGLStyleValue` class takes a generic parameter `T` that indicates the | ||
| Foundation class being wrapped by this class. Common values for `T` include: | ||
|
|
@@ -62,32 +63,70 @@ MGL_EXPORT | |
| #pragma mark Function values | ||
|
|
||
| /** | ||
| Creates and returns an `MGLCameraStyleFunction` object representing a linear camera | ||
| function with one or more stops. | ||
|
|
||
| @param stops A dictionary associating zoom levels with style values. | ||
| @return An `MGLCameraStyleFunction` object with the given stops. | ||
| */ | ||
| + (instancetype)valueWithStops:(NSDictionary<NSNumber *, MGLStyleValue<T> *> *)stops __attribute__((deprecated("Use +[MGLStyleValue valueWithInterpolationMode:cameraStops:options:]"))); | ||
|
|
||
| /** | ||
| Creates and returns an `MGLCameraStyleFunction` object representing a camera | ||
| function with an exponential interpolation base and one or more stops. | ||
|
|
||
| @param interpolationBase The exponential base of the interpolation curve. | ||
| @param stops A dictionary associating zoom levels with style values. | ||
| @return An `MGLCameraStyleFunction` object with the given interpolation base and stops. | ||
| */ | ||
| + (instancetype)valueWithInterpolationBase:(CGFloat)interpolationBase stops:(NSDictionary<NSNumber *, MGLStyleValue<T> *> *)stops __attribute__((deprecated("Use +[MGLStyleValue valueWithInterpolationMode:cameraStops:options:]"))); | ||
|
|
||
| /** | ||
| Creates and returns an `MGLCameraStyleFunction` object representing a camera function | ||
| with one or more stops. | ||
|
|
||
| @param interpolationMode The mode used to interpolate property values between | ||
| map zoom level changes. | ||
| @param cameraStops A dictionary associating zoom levels with style values. | ||
| @param options A dictionary containing `MGLStyleFunctionOption` values that | ||
| specify how a function is applied. | ||
| @return An `MGLCameraStyleFunction` object with the given interpolation mode, | ||
| camera stops, and options. | ||
| */ | ||
| + (instancetype)valueWithInterpolationMode:(MGLInterpolationMode)interpolationMode cameraStops:(NS_DICTIONARY_OF(id, MGLStyleValue<T> *) *)cameraStops options:(nullable NS_DICTIONARY_OF(MGLStyleFunctionOption, id) *)options; | ||
|
|
||
| /** | ||
| Creates and returns an `MGLSourceStyleFunction` object representing a source function. | ||
|
|
||
| @param interpolationMode The mode used to interpolate property values over a | ||
| range of feature attribute values. | ||
| @param sourceStops A dictionary associating feature attributes with style values. | ||
| @param attributeName Specifies the feature attribute to take as the function | ||
| input. | ||
| @param options A dictionary containing `MGLStyleFunctionOption` values that | ||
| specify how a function is applied. | ||
| @return An `MGLSourceStyleFunction` object with the given interpolation mode, | ||
| source stops, attribute name, and options. | ||
| */ | ||
| + (instancetype)valueWithInterpolationMode:(MGLInterpolationMode)interpolationMode sourceStops:(nullable NS_DICTIONARY_OF(id, MGLStyleValue<T> *) *)sourceStops attributeName:(NSString *)attributeName options:(nullable NS_DICTIONARY_OF(MGLStyleFunctionOption, id) *)options; | ||
|
|
||
| /** | ||
| Creates and returns an `MGLCompositeStyleFunction` object representing a composite | ||
| function made up of one or more outer stops interpreted as a camera function | ||
| with a single inner stop at each zoom level that is interpreted as a source | ||
| function. | ||
|
|
||
| @param interpolationMode The mode used to interpolate property values over a | ||
| range of feature attribute values for each outer zoom level. | ||
| @param sourceStops A dictionary associating feature attributes with style values. | ||
| @param attributeName Specifies the feature attribute to take as the function | ||
| input. | ||
| @param options A dictionary containing `MGLStyleFunctionOption` values that | ||
| specify how a function is applied. | ||
| @return An `MGLCompositeStyleFunction` object with the given interpolation mode, | ||
| composite stops, attribute name, and options. | ||
| */ | ||
| + (instancetype)valueWithInterpolationMode:(MGLInterpolationMode)interpolationMode compositeStops:(NS_DICTIONARY_OF(id, NS_DICTIONARY_OF(id, MGLStyleValue<T> *) *) *)compositeStops attributeName:(NSString *)attributeName options:(nullable NS_DICTIONARY_OF(MGLStyleFunctionOption, id) *)options; | ||
|
There was a problem hiding this comment. If each stop is “interpreted as a source function”, should the type of There was a problem hiding this comment. This was me doing a poor job of trying to clarify the opposite: "composite" in this case means a composite of stops dictionaries not functions (see discussion in #7596 (comment)). In d46559a, I punted on trying to explain this in the class factory method in favor of the explanation in the |
||
|
|
||
| @end | ||
|
|
||
|
|
@@ -135,77 +174,261 @@ MGL_EXPORT | |
|
|
||
| @end | ||
|
|
||
| /** | ||
| An `MGLStyleFunction` is a is an abstract superclass for functions that are | ||
| defined by an `MGLCameraStyleFunction`, `MGLSourceStyleFunction`, or | ||
| `MGLCompositeStyleFunction` object. | ||
|
|
||
| Do not create instances of this class directly, and do not create your own | ||
| subclasses of this class. Instead, use one of the class factory methods in | ||
| `MGLStyleValue` to create instances of the following concrete subclasses: | ||
| `MGLCameraStyleFunction`, `MGLSourceStyleFunction`, and | ||
| `MGLCompositeStyleFunction`. | ||
|
|
||
| The `MGLStyleFunction` class takes a generic parameter `T` that indicates the | ||
| Foundation class being wrapped by this class. | ||
| */ | ||
| MGL_EXPORT | ||
| @interface MGLStyleFunction<T> : MGLStyleValue<T> | ||
|
|
||
| #pragma mark Accessing the Parameters of a Function | ||
|
|
||
| /** | ||
| The modes used to interpolate property values between map zoom level changes or | ||
| over a range of feature attribute values. | ||
| */ | ||
| @property (nonatomic) MGLInterpolationMode interpolationMode; | ||
|
There was a problem hiding this comment. Could we avoid effectively adding an There was a problem hiding this comment. In ee89e94 I removed it in There was a problem hiding this comment.
Ah, I misunderstood. In that case, it’s fine (and preferable) to have it in MGLStyleFunction to avoid duplication. There was a problem hiding this comment. Yeah. For now, it'll be a bit of a lie, but still reasonable.
|
||
|
|
||
| /** | ||
| A dictionary associating zoom levels with style values. | ||
| */ | ||
| @property (nonatomic, copy) NSDictionary *stops; | ||
|
|
||
| /** | ||
| The exponential interpolation base of the function’s interpolation curve. | ||
| */ | ||
|
There was a problem hiding this comment. Document the fact that |
||
| @property (nonatomic) CGFloat interpolationBase; | ||
|
|
||
| @end | ||
|
There was a problem hiding this comment. For backwards compatibility, MGLStyleFunction also needs the initializers that it had in v3.4.0. These initializers can be marked as deprecated. There was a problem hiding this comment. This will probably look a bit strange no matter what we do. I think 406e647 is a workable solution until a semver bump when we can more officially make this class abstract. The initializers have been brought back and an actual instance of |
||
|
|
||
| /** | ||
| An `MGLCameraStyleFunction` is a value function defining a style value that changes | ||
| as the zoom level changes. The layout and paint attribute properties of an | ||
| `MGLStyleLayer` object can be set to `MGLCameraStyleFunction` objects. Use a zoom | ||
| level function to create the illusion of depth and control data density. | ||
|
There was a problem hiding this comment. “Zoom level functions” are now known as “camera functions”. |
||
|
|
||
| The `MGLCameraStyleFunction` class takes a generic parameter `T` that indicates the | ||
| Foundation class being wrapped by this class. | ||
| */ | ||
| MGL_EXPORT | ||
| @interface MGLCameraStyleFunction<T> : MGLStyleFunction<T> | ||
|
|
||
| #pragma mark Creating a Camera Function | ||
|
|
||
| /** | ||
| Creates and returns an `MGLCameraStyleFunction` object representing a zoom level | ||
| function with one or more stops. | ||
|
|
||
| @param interpolationMode The mode used to interpolate property values between | ||
| map zoom level changes. | ||
| @param stops A dictionary associating zoom levels with style values. | ||
| @param options A dictionary containing `MGLStyleFunctionOption` values that | ||
| specify how a function is applied. | ||
| @return An `MGLCameraStyleFunction` object with the given interpolation mode, | ||
| camera stops, and options. | ||
| */ | ||
| + (instancetype)functionWithInterpolationMode:(MGLInterpolationMode)interpolationMode stops:(NS_DICTIONARY_OF(id, MGLStyleValue<T> *) *)stops options:(nullable NS_DICTIONARY_OF(MGLStyleFunctionOption, id) *)options; | ||
|
|
||
| #pragma mark Initializing a Camera Function | ||
|
|
||
| /** | ||
| Returns an `MGLCameraStyleFunction` object representing a zoom level | ||
| function with one or more stops. | ||
|
|
||
| @param interpolationMode The mode used to interpolate property values between | ||
| map zoom level changes. | ||
| @param stops A dictionary associating zoom levels with style values. | ||
| @param options A dictionary containing `MGLStyleFunctionOption` values that | ||
| specify how a function is applied. | ||
| @return An `MGLCameraStyleFunction` object with the given interpolation mode, | ||
| camera stops, and options. | ||
| */ | ||
| - (instancetype)initWithInterpolationMode:(MGLInterpolationMode)interpolationMode stops:(NS_DICTIONARY_OF(id, MGLStyleValue<T> *) *)stops options:(nullable NS_DICTIONARY_OF(MGLStyleFunctionOption, id) *)options NS_DESIGNATED_INITIALIZER; | ||
|
|
||
| #pragma mark Accessing the Parameters of a Camera Function | ||
|
|
||
| /** | ||
| A dictionary associating zoom levels with style values. | ||
|
|
||
| Each of the function’s stops is represented by one key-value pair in the | ||
| dictionary. Each key in the dictionary is an `NSNumber` object containing a | ||
| floating-point zoom level. Each value in the dictionary is an `MGLStyleValue` | ||
| object containing the value of the style attribute when the map is at the | ||
| associated zoom level. An `MGLStyleFunction` object may not be used recursively | ||
| as a stop value. | ||
| */ | ||
| @property (nonatomic, copy) NS_DICTIONARY_OF(id, MGLStyleValue<T> *) *stops; | ||
|
|
||
| @end | ||
|
|
||
| /** | ||
| An `MGLSourceStyleFunction` is a value function defining a style value that | ||
| changes with its properties. The layout and paint attribute properties of an | ||
| `MGLStyleLayer` object can be set to `MGLSourceStyleFunction` objects. | ||
| Use source functions to visually differentate types of features within the same | ||
| layer or create data visualizations. | ||
|
|
||
| The `MGLSourceStyleFunction` class takes a generic parameter `T` that indicates the | ||
| Foundation class being wrapped by this class. | ||
| */ | ||
| MGL_EXPORT | ||
| @interface MGLSourceStyleFunction<T> : MGLStyleFunction<T> | ||
|
|
||
| #pragma mark Creating a Source Function | ||
|
|
||
| /** | ||
| Creates and returns an `MGLSourceStyleFunction` object representing a source | ||
| function. | ||
|
|
||
| @param interpolationMode The mode used to interpolate property values over a | ||
| range of feature attribute values. | ||
| @param sourceStops A dictionary associating feature attributes with style values. | ||
| @param attributeName Specifies the feature attribute to take as the function | ||
| input. | ||
| @param options A dictionary containing `MGLStyleFunctionOption` values that | ||
| specify how a function is applied. | ||
| @return An `MGLSourceStyleFunction` object with the given interpolation mode, | ||
| source stops, attribute name, and options. | ||
| */ | ||
| + (instancetype)functionWithInterpolationMode:(MGLInterpolationMode)interpolationMode stops:(nullable NS_DICTIONARY_OF(id, MGLStyleValue<T> *) *)stops attributeName:(NSString *)attributeName options:(nullable NS_DICTIONARY_OF(MGLStyleFunctionOption, id) *)options; | ||
|
|
||
| #pragma mark Initializing a Source Function | ||
|
|
||
| /** | ||
| Returns an `MGLSourceStyleFunction` object representing a source function. | ||
|
|
||
| @param interpolationMode The mode used to interpolate property values over a | ||
| range of feature attribute values. | ||
| @param sourceStops A dictionary associating feature attributes with style values. | ||
| @param attributeName Specifies the feature attribute to take as the function | ||
| input. | ||
| @param options A dictionary containing `MGLStyleFunctionOption` values that | ||
| specify how a function is applied. | ||
| @return An `MGLSourceStyleFunction` object with the given interpolation mode, | ||
| source stops, attribute name, and options. | ||
| */ | ||
| - (instancetype)initWithInterpolationMode:(MGLInterpolationMode)interpolationMode stops:(nullable NS_DICTIONARY_OF(id, MGLStyleValue<T> *) *)stops attributeName:(NSString *)attributeName options:(nullable NS_DICTIONARY_OF(MGLStyleFunctionOption, id) *)options NS_DESIGNATED_INITIALIZER; | ||
|
|
||
| #pragma mark Accessing the Parameters of a Source Function | ||
|
|
||
| /** | ||
| A string that specifies the feature attribute key whose value be used as the function | ||
| input. | ||
| */ | ||
| @property (nonatomic, copy) NSString *attributeName; | ||
|
|
||
| /** | ||
| A dictionary associating attribute values with style values. | ||
|
|
||
| Each of the function’s stops is represented by one key-value pair in the | ||
| dictionary. Each key in the dictionary is an object representing a feature | ||
| attribute key. Each value in the dictionary is an `MGLStyleValue` object | ||
| containing the value to use when the function is given the associated | ||
| attribute key. An `MGLStyleFunction` object may not be used recursively | ||
| as a stop value. | ||
| */ | ||
| @property (nonatomic, copy, nullable) NS_DICTIONARY_OF(id, MGLStyleValue<T> *) *stops; | ||
|
|
||
| /** | ||
| An `MGLStyleValue` object containing the default value to use when there is | ||
| no input to provide to the function. | ||
| */ | ||
| @property (nonatomic, nullable) MGLStyleValue<T> *defaultValue; | ||
|
|
||
| @end | ||
|
|
||
| /** | ||
| An `MGLCompositeStyleFunction` is a value function defining a style value that | ||
| changes with the feature attributes at each map zoom level. The layout and paint | ||
| attribute properties of an `MGLStyleLayer` object can be set to | ||
| `MGLCompositeStyleFunction` objects. Use composite functions to allow the | ||
| appearance of a map feature to change with both its attributes and the map zoom | ||
| level. | ||
|
|
||
| The `MGLCompositeStyleFunction` class takes a generic parameter `T` that indicates the | ||
| Foundation class being wrapped by this class. | ||
| */ | ||
| MGL_EXPORT | ||
| @interface MGLCompositeStyleFunction<T> : MGLStyleFunction<T> | ||
|
|
||
| #pragma mark Creating a Composite Function | ||
|
|
||
| /** | ||
| Creates and returns an `MGLCompositeStyleFunction` object representing a composite | ||
| function made up of one or more outer stops interpreted as a camera function | ||
| with a single inner stop at each zoom level that is interpreted as a source | ||
| function. | ||
|
|
||
| @param interpolationMode The mode used to interpolate property values over a | ||
| range of feature attribute values for each outer zoom level. | ||
| @param sourceStops A dictionary associating feature attributes with style values. | ||
| @param attributeName Specifies the feature attribute to take as the function | ||
| input. | ||
| @param options A dictionary containing `MGLStyleFunctionOption` values that | ||
| specify how a function is applied. | ||
| @return An `MGLCompositeStyleFunction` object with the given interpolation mode, | ||
| composite stops, attribute name, and options. | ||
| */ | ||
| + (instancetype)functionWithInterpolationMode:(MGLInterpolationMode)interpolationMode stops:(NS_DICTIONARY_OF(id, NS_DICTIONARY_OF(id, MGLStyleValue<T> *) *) *)stops attributeName:(NSString *)attributeName options:(nullable NS_DICTIONARY_OF(MGLStyleFunctionOption, id) *)options; | ||
|
|
||
| #pragma mark Initializing a Composite Function | ||
|
|
||
| /** | ||
| Returns an `MGLCompositeStyleFunction` object representing a composite | ||
| function made up of one or more outer stops interpreted as a camera function | ||
| with a single inner stop at each zoom level that is interpreted as a source | ||
| function. | ||
|
|
||
| @param interpolationMode The mode used to interpolate property values over a | ||
| range of feature attribute values for each outer zoom level. | ||
| @param sourceStops A dictionary associating feature attributes with style values. | ||
| @param attributeName Specifies the feature attribute to take as the function | ||
| input. | ||
| @param options A dictionary containing `MGLStyleFunctionOption` values that | ||
| specify how a function is applied. | ||
| @return An `MGLCompositeStyleFunction` object with the given interpolation mode, | ||
| composite stops, attribute name, and options. | ||
| */ | ||
| - (instancetype)initWithInterpolationMode:(MGLInterpolationMode)interpolationMode stops:(NS_DICTIONARY_OF(id, NS_DICTIONARY_OF(id, MGLStyleValue<T> *) *) *)stops attributeName:(NSString *)attributeName options:(nullable NS_DICTIONARY_OF(MGLStyleFunctionOption, id) *)options NS_DESIGNATED_INITIALIZER; | ||
|
|
||
| #pragma mark Accessing the Parameters of a Composite Function | ||
|
|
||
| /** | ||
| A string that specifies the feature attribute key whose value be used as the function | ||
| input. | ||
| */ | ||
| @property (nonatomic, copy) NSString *attributeName; | ||
|
|
||
| /** | ||
| A dictionary associating attribute values with style values. | ||
|
|
||
| Each of the function’s stops is represented by one key-value pair in the | ||
| dictionary. Each key in the dictionary is an `NSNumber` object containing a | ||
| floating-point zoom level. Each value in the dictionary is an inner nested | ||
| dictionary. The nested dictionary key is an object representing a feature | ||
| attribute key. The nested dictionary value is an `MGLStyleValue` object | ||
| containing the value to use when the function is given the associated attribute | ||
| key at the outer zoom level. An `MGLStyleFunction` object may not be used | ||
| recursively as a value inside the nested dictionary. | ||
| */ | ||
| @property (nonatomic, copy) NS_DICTIONARY_OF(id, NS_DICTIONARY_OF(id, MGLStyleValue<T> *) *) *stops; | ||
|
|
||
| /** | ||
| An `MGLStyleValue` object containing the default value to use when there is | ||
| no input to provide to the function. | ||
| */ | ||
| @property (nonatomic, nullable) MGLStyleValue<T> *defaultValue; | ||
|
|
||
| @end | ||
|
|
||
| NS_ASSUME_NONNULL_END | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Remember to use the
NS_…_OFmacros until we drop iOS 8 support.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It looks like we forgot to do this in the
3.4.0release. In fbb8068 and 3b90d85 I updated the deprecated methods and everything in the resurrectedMGLStyleFunctionto use the macro. The only use ofNSDictionary(with no lightweight generic attributes) inMGLStyleValuenow is for thestopsproperty ofMGLStyleFunctionfor reasons already discussed in this PR.