components/Typography/src/MDCTypography.h

// Copyright 2015-present the Material Components for iOS authors. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#import <UIKit/UIKit.h>

API_DEPRECATED_BEGIN("🤖👀 Use typography tokens instead. "
                     "See go/material-ios-typography/gm2-migration for more details."
                     "This has go/material-ios-migrations#scriptable-potential 🤖👀. ",
                     ios(12, 12))

/**
 MDCTypography uses this protocol to delegate responsibility of loading the custom fonts.

 The spec defines the Roboto font family and uses three fonts in the named styles. Use this
 protocol to define your own fonts if there is a brand need.

 @warning This protocol will soon be deprecated. Consider using MDCTypographyScheme from the
 schemes/Typography component instead.

 @see https://material.io/go/design-typography#typography-styles
 */
@protocol MDCTypographyFontLoading <NSObject>
@required

/** Asks the receiver to return a font with a light weight. FontSize must be larger tha 0. */
- (nullable UIFont *)lightFontOfSize:(CGFloat)fontSize;

/** Asks the receiver to return a font with a normal weight. FontSize must be larger tha 0. */
- (nonnull UIFont *)regularFontOfSize:(CGFloat)fontSize;

/** Asks the receiver to return a font with a medium weight. FontSize must be larger tha 0. */
- (nullable UIFont *)mediumFontOfSize:(CGFloat)fontSize;

@optional

/** Asks the receiver to return a font with a bold weight. FontSize must be larger tha 0. */
- (nonnull UIFont *)boldFontOfSize:(CGFloat)fontSize;

/** Asks the receiver to return an italic font. FontSize must be larger tha 0. */
- (nonnull UIFont *)italicFontOfSize:(CGFloat)fontSize;

/** Asks the receiver to return a font with an italic bold weight. FontSize must be larger tha 0. */
- (nullable UIFont *)boldItalicFontOfSize:(CGFloat)fontSize;

/** Returns a bold version of the specified font. */
- (nonnull UIFont *)boldFontFromFont:(nonnull UIFont *)font;

/** Returns an italic version of the specified font. */
- (nonnull UIFont *)italicFontFromFont:(nonnull UIFont *)font;
/**
 Asks the receiver to determine if a particular font would be considered "large" for the purposes of
 calculating contrast ratios.

 Large fonts are defined as greater than 18pt normal or 14pt bold.
 For more see: https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html

 @param font The font to examine.
 @return YES if the font is considered "large".
 */
- (BOOL)isLargeForContrastRatios:(nonnull UIFont *)font;

@end

/**
 Typographic constants and helpers.

 To use these fonts, you must add MaterialTypography.bundle to your target.

 @warning This class will soon be deprecated. Consider using MDCTypographyScheme from the
 schemes/Typography component instead.

 @see https://material.io/go/design-typography#typography-styles
 */
@interface MDCTypography : NSObject

#pragma mark - Font loader access

/** Get the current font loader. */
+ (nonnull id<MDCTypographyFontLoading>)fontLoader;

#pragma mark - Display fonts (extra large fonts)

/** Returns the display 4 font. (largest of the display font sizes) */
+ (nonnull UIFont *)display4Font;

/** Returns the display 3 font. (second largest of the display font sizes) */
+ (nonnull UIFont *)display3Font;

/** Returns the display 2 font. (third largest of the display font sizes) */
+ (nonnull UIFont *)display2Font;

/** Returns the display 1 font. (smallest of the display font sizes) */
+ (nonnull UIFont *)display1Font;

#pragma mark - Common UI fonts

/** Returns the headline font. */
+ (nonnull UIFont *)headlineFont;

/** Returns the title font. */
+ (nonnull UIFont *)titleFont;

/** Returns the subhead font. (subtitle) */
+ (nonnull UIFont *)subheadFont;

/** Returns the body 2 text font. (bold text) */
+ (nonnull UIFont *)body2Font;

/** Returns the body 1 text font. (normal text) */
+ (nonnull UIFont *)body1Font;

/** Returns the caption font. (a small font for image captions) */
+ (nonnull UIFont *)captionFont;

/** Returns a font for buttons. */
+ (nonnull UIFont *)buttonFont;

/**
 Asks the receiver to determine if a particular font would be considered "large" for the purposes of
 calculating contrast ratios.

 Large fonts are defined as greater than 18pt normal or 14pt bold. If the passed font is nil, then
 this method returns NO.
 For more see: https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html

 @param font The font to examine.
 @return YES if the font is non-nil and is considered "large".
 */
+ (BOOL)isLargeForContrastRatios:(nonnull UIFont *)font;

@end

/**
 MDCSystemFontLoader allows you to use the system font for @c MDCTypography.

 @warning This class will soon be deprecated. Consider using MDCTypographyScheme from the
 schemes/Typography component instead.

 #### Example

 ```
 [MDCTypography setFontLoader:[[MDCSystemFontLoader alloc] init]];
 ```
 */
@interface MDCSystemFontLoader : NSObject <MDCTypographyFontLoading>
@end

API_DEPRECATED_END