diff --git a/docs.json b/docs.json index 40eea0779..e55b566aa 100644 --- a/docs.json +++ b/docs.json @@ -1425,6 +1425,7 @@ "ui-kit/ios/component-styling", "ui-kit/ios/message-bubble-styling", "ui-kit/ios/localize", + "ui-kit/ios/rtl-support", "ui-kit/ios/sound-manager" ] }, diff --git a/ui-kit/ios/localize.mdx b/ui-kit/ios/localize.mdx index 9e6197848..435ee0816 100644 --- a/ui-kit/ios/localize.mdx +++ b/ui-kit/ios/localize.mdx @@ -25,6 +25,10 @@ CometChat UI Kit provides language localization to adapt to the language of a sp `CometChatLocalize` is a class that includes methods related to locale. Developers can use these methods to change the language of the UI Kit library. + +Setting a language does not change the layout direction. To lay out the UI Kit right to left, see [RTL Support](/ui-kit/ios/rtl-support). + + ### Supported Languages The UI Kit supports 17 languages for localization: diff --git a/ui-kit/ios/rtl-support.mdx b/ui-kit/ios/rtl-support.mdx new file mode 100644 index 000000000..ae40dae91 --- /dev/null +++ b/ui-kit/ios/rtl-support.mdx @@ -0,0 +1,262 @@ +--- +title: "RTL Support" +sidebarTitle: "RTL Support" +description: "Set the layout direction of the CometChat iOS UI Kit for right-to-left languages, for the whole kit or for a single component" +--- + + + +| Field | Value | +| --- | --- | +| Platform | iOS UI Kit | +| Kit-Level Direction | `CometChatUIKit.set(layoutDirection: .rightToLeft)` | +| Direction at Start-Up | `UIKitSettings().set(layoutDirection: .rightToLeft)` | +| Component-Level Direction | `messageList.set(layoutDirection: .leftToRight)` | +| Type (Kit and Component Level) | `UIUserInterfaceLayoutDirection?` (`.rightToLeft`, `.leftToRight`, `nil`) | +| Type (Start-Up) | `UIUserInterfaceLayoutDirection`, not optional (`.rightToLeft`, `.leftToRight`) | +| Default | `nil`: the kit follows your app's layout direction | +| Language | Separate setting: `CometChatLocalize.set(locale:)` does not change the layout direction | +| Applies To | Kit-level value applies to components created after the call | +| Always Left to Right | Audio and video players, waveforms, playback controls, durations, code blocks | + + + +## Overview + +CometChat UI Kit supports layouts for right-to-left (RTL) languages such as Arabic. You choose the layout direction of the kit's components with `set(layoutDirection:)`, either for the whole kit or for a single component. + +The direction is a `UIUserInterfaceLayoutDirection?` value: + +| Value | Behavior | +|-------|----------| +| `.rightToLeft` | The kit's components lay out right to left | +| `.leftToRight` | The kit's components lay out left to right | +| `nil` | Not set. The kit follows your app's layout direction. This is the default | + +A direction you set applies to the kit's components only. Your app's own screens do not change. + + +With no direction set, the kit follows your app, as any other UIKit view does. iOS lays out an app right to left when the app runs in a right-to-left language, which requires your app to include that localization, or when your app sets `UIView.appearance().semanticContentAttribute`. + + +--- + +## Language and Direction Are Separate + +Language and layout direction are two independent settings: + +| Setting | Method | What it changes | +|---------|--------|-----------------| +| Language | `CometChatLocalize.set(locale:)` | The text the kit shows. It does not change the layout direction | +| Direction | `CometChatUIKit.set(layoutDirection:)` | How the kit's components lay out. It does not change the language | + +Combine them to get the result you need: + +| Goal | Language | Direction | +|------|----------|-----------| +| Arabic text in an RTL kit | `CometChatLocalize.set(locale: .arabic)` | `CometChatUIKit.set(layoutDirection: .rightToLeft)` | +| RTL kit with English text | `CometChatLocalize.set(locale: .english)` | `CometChatUIKit.set(layoutDirection: .rightToLeft)` | +| Arabic text in an LTR kit | `CometChatLocalize.set(locale: .arabic)` | `CometChatUIKit.set(layoutDirection: .leftToRight)` | +| Kit follows your app | Any | Not set (`nil`) | + + + +```swift lines +// Show Arabic text and lay the kit out right to left +CometChatLocalize.set(locale: .arabic) +CometChatUIKit.set(layoutDirection: .rightToLeft) +``` + + + +See [Localization](/ui-kit/ios/localize) for the language setting. + +--- + +## Set the Direction + +You can set the direction at three levels. + +### 1. Kit Level + +`CometChatUIKit.set(layoutDirection:)` sets the direction for every component the kit creates after the call. Pass `nil` to go back to following your app. + + + +```swift lines +// Lay out all kit components right to left +CometChatUIKit.set(layoutDirection: .rightToLeft) + +// Go back to following the app +CometChatUIKit.set(layoutDirection: nil) +``` + + + +### 2. At Start-Up + +`UIKitSettings.set(layoutDirection:)` gives the direction with the rest of your settings. The kit applies it when `CometChatUIKit.init(uiKitSettings:)` succeeds. If the initialization fails, the direction is not applied. + + + +```swift lines +let uikitSettings = UIKitSettings() + .set(appID: "APP_ID") // Replace with your App ID + .set(region: "REGION") // Replace with your Region + .set(authKey: "AUTH_KEY") // Replace with your Auth Key (dev only) + .set(layoutDirection: .rightToLeft) + .build() + +CometChatUIKit.init(uiKitSettings: uikitSettings) { result in + switch result { + case .success: + debugPrint("CometChat initialized") + case .failure(let error): + debugPrint("Initialization failed: \(error.localizedDescription)") + } +} +``` + + + +`UIKitSettings.set(layoutDirection:)` takes `.rightToLeft` or `.leftToRight`. To follow your app, leave it out. + +### 3. Component Level + +A component's own `set(layoutDirection:)` sets the direction of that component only, and wins over the kit-level value. Pass `nil` to inherit again. + + + +```swift lines +// The kit is right to left +CometChatUIKit.set(layoutDirection: .rightToLeft) + +// This conversations screen is left to right +let conversations = CometChatConversations() +conversations.set(layoutDirection: .leftToRight) + +// This message list is right to left, whatever the kit-level value is +let messageList = CometChatMessageList() +messageList.set(user: user) +messageList.set(layoutDirection: .rightToLeft) +``` + + + +`set(layoutDirection:)` is available on every list screen built on `CometChatListBase`, and on the other components below: + +| Type | Components | +|------|------------| +| List screens | [CometChatConversations](/ui-kit/ios/conversations), [CometChatUsers](/ui-kit/ios/users), [CometChatGroups](/ui-kit/ios/groups), [CometChatGroupMembers](/ui-kit/ios/group-members), [CometChatCallLogs](/ui-kit/ios/call-logs), [CometChatSavedMessages](/ui-kit/ios/saved-messages), [CometChatPinnedMessages](/ui-kit/ios/pinned-messages), [CometChatNotificationFeed](/ui-kit/ios/notification-feed), `CometChatMessageInformation` | +| Messages | [CometChatMessageHeader](/ui-kit/ios/message-header), [CometChatMessageList](/ui-kit/ios/message-list), [CometChatMessageComposer](/ui-kit/ios/message-composer), [CometChatCompactMessageComposer](/ui-kit/ios/compact-message-composer), [CometChatThreadedMessageHeader](/ui-kit/ios/threaded-messages-header), `CometChatMessagePreview`, [CometChatSearch](/ui-kit/ios/search) | +| Calls | [CometChatIncomingCall](/ui-kit/ios/incoming-call), [CometChatOutgoingCall](/ui-kit/ios/outgoing-call), [CometChatOngoingCall](/ui-kit/ios/ongoing-call), [CometChatCallButtons](/ui-kit/ios/call-buttons) | +| AI | [CometChatAIAssistanceChatHistory](/ui-kit/ios/ai-assistant-chat-history), `CometChatAIConversationStarter`, `CometChatAISmartReply`, `CometChatAIConversationSummary` | +| Other screens and views | `CometChatCreatePoll`, `CometChatScopeChange`, `CometChatReactionList`, `CometChatActionSheet`, `CometChatMediaViewer`, `CometChatMediaRecorder`, `CometChatEmojiKeyboard`, `CometChatStickerKeyboard` | + +Base views such as avatars, message bubbles, receipts, dates and badges do not have their own `set(layoutDirection:)`. Inside a component they take that component's direction. Used on their own, they follow the kit-level value. + +--- + +## How the Direction Is Resolved + +For each view, the kit uses the first of these that applies: + +1. Audio and video players, and the other parts listed in [What Stays Left to Right](#what-stays-left-to-right), are always left to right +2. The component's own `set(layoutDirection:)` value +3. The direction of the nearest enclosing kit component +4. The kit-level value +5. Your app's layout direction + +Screens, alerts and sheets that a component opens take that component's direction. + +### Changes Apply to New Components + +A component reads the kit-level value once, when it is created. A change made with `CometChatUIKit.set(layoutDirection:)` applies to components created afterwards. Components that already exist keep the direction they were created with. + +After you change the kit-level direction, build your open screens again: + + + +```swift lines +func applyKitDirection(_ direction: UIUserInterfaceLayoutDirection?, in window: UIWindow) { + CometChatUIKit.set(layoutDirection: direction) + + // Existing components keep their direction, so create the screen again + let conversations = CometChatConversations() + window.rootViewController = UINavigationController(rootViewController: conversations) +} +``` + + + +### Order of Calls Around Init + +`CometChatUIKit.init(uiKitSettings:)` applies the direction from its settings when the initialization succeeds. This affects a kit-level call made around it: + +| When you call `CometChatUIKit.set(layoutDirection:)` | Result | +|------|--------| +| Before you call `CometChatUIKit.init(uiKitSettings:)` | Replaced when the initialization succeeds. The kit uses the direction in the settings, or follows your app if the settings have none | +| After you call `CometChatUIKit.init(uiKitSettings:)` | Wins over the direction in the settings, whether it runs before or after the initialization completes | + + +If you set the direction before you initialize the kit, give it with `UIKitSettings.set(layoutDirection:)`. A `CometChatUIKit.set(layoutDirection:)` call made before `CometChatUIKit.init(uiKitSettings:)` is replaced when the initialization succeeds. + + +--- + +## What Stays Left to Right + +Media playback reads left to right, as in system players. The following parts do not mirror under any direction setting, including when your app itself runs right to left: + +| Part | Behavior | +|------|----------| +| Audio bubble | The player, its controls and its waveform stay left to right | +| Video bubble | The play control and thumbnail overlay stay left to right | +| Video player in the media viewer | The player and its controls stay left to right | +| Audio files in a multi-attachment bubble | Each audio row and its slider stay left to right | +| Video tiles in a multi-attachment bubble | The play control and duration stay left to right | +| Attachments in the composer | The audio player, and a video's play overlay and duration, stay left to right | +| Voice recorder | The waveform, the record, play and pause controls, and the duration stay left to right | +| Code blocks | Code stays left to right | + +The rest of the voice recorder does mirror. In a right-to-left layout, the row of controls is reversed: the send button is on the left, and the delete button is on the right. + +--- + +## Message Text and Icons + +### Message Text Follows Its Own Language + +The kit does not force a direction on message text. Each paragraph is aligned and read from its own language: an English message in a right-to-left chat still reads left to right, and an Arabic message in a left-to-right chat still reads right to left. + +### Directional Icons Mirror + +The kit's built-in icons that point in a direction mirror in a right-to-left layout. Examples are the back button of the message header, the send button of the composer, the reply and thread icons, and the call direction arrows. + +An icon you supply through a style is drawn as you provide it. To make your own icon mirror, use UIKit's `imageFlippedForRightToLeftLayoutDirection()`: + + + +```swift lines +// A custom back icon that mirrors in a right-to-left layout +CometChatMessageHeader.style.backButtonIcon = UIImage(systemName: "arrow.left")? + .imageFlippedForRightToLeftLayoutDirection() +``` + + + +--- + +## Next Steps + + + + Set the language of the UI Kit and override its strings + + + Customize the visual appearance of UI components + + + Apply custom styles to individual components + +