com.facebook.react.uimanager

Class UIManagerModule

java.lang.Object

com.facebook.react.bridge.BaseJavaModule

com.facebook.react.bridge.ReactContextBaseJavaModule

com.facebook.react.uimanager.UIManagerModule

All Implemented Interfaces:

LifecycleEventListener, NativeModule, OnBatchCompleteListener

public class UIManagerModule
extends ReactContextBaseJavaModule
implements OnBatchCompleteListener, LifecycleEventListener

Native module to allow JS to create and update native Views.

== Transactional Requirement ==

A requirement of this class is to make sure that transactional UI updates occur all at once, meaning that no intermediate state is ever rendered to the screen. For example, if a JS application update changes the background of View A to blue and the width of View B to 100, both need to appear at once. Practically, this means that all UI update code related to a single transaction must be executed as a single code block on the UI thread. Executing as multiple code blocks could allow the platform UI system to interrupt and render a partial UI state.

To facilitate this, this module enqueues operations that are then applied to native view hierarchy through NativeViewHierarchyManager at the end of each transaction.

== CSSNodes ==

In order to allow layout and measurement to occur on a non-UI thread, this module also operates on intermediate CSSNode objects that correspond to a native view. These CSSNode are able to calculate layout according to their styling rules, and then the resulting x/y/width/height of that layout is scheduled as an operation that will be applied to native view hierarchy at the end of current batch.

TODO(5241856): Investigate memory usage of creating many small objects in UIManageModule and consider implementing a pool TODO(5483063): Don't dispatch the view hierarchy at the end of a batch if no UI changes occurred

Nested Class Summary

Nested classes/interfaces inherited from interface com.facebook.react.bridge.NativeModule

NativeModule.NativeMethod

Field Summary

Fields inherited from class com.facebook.react.bridge.BaseJavaModule

METHOD_TYPE_REMOTE, METHOD_TYPE_REMOTE_ASYNC

Constructor Summary

Constructors

Constructor and Description
UIManagerModule(ReactApplicationContext reactContext, java.util.List<ViewManager> viewManagerList, UIImplementation uiImplementation)

Method Summary

Methods

Modifier and Type	Method and Description
void	addAnimation(int reactTag, int animationID, Callback onSuccess) Adds an Animation previously registered with registerAnimation(com.facebook.react.animation.Animation) to a View and starts it
int	addMeasuredRootView(SizeMonitoringFrameLayout rootView) Registers a new root view.
void	clearJSResponder()
void	configureNextLayoutAnimation(ReadableMap config, Callback success, Callback error) Configure an animation to be used for the native layout changes, and native views creation.
void	createView(int tag, java.lang.String className, int rootViewTag, ReadableMap props)
void	dispatchViewManagerCommand(int reactTag, int commandId, ReadableArray commandArgs)
void	findSubviewIn(int reactTag, ReadableArray point, Callback callback) Find the touch target child native view in the supplied root view hierarchy, given a react target location.
java.util.Map<java.lang.String,java.lang.Object>	getConstants()
EventDispatcher	getEventDispatcher()
java.lang.String	getName()
void	manageChildren(int viewTag, ReadableArray moveFrom, ReadableArray moveTo, ReadableArray addChildTags, ReadableArray addAtIndices, ReadableArray removeFrom) Interface for adding/removing/moving views within a parent view from JS.
void	measure(int reactTag, Callback callback) Determines the location on screen, width, and height of the given view and returns the values via an async callback.
void	measureLayout(int tag, int ancestorTag, Callback errorCallback, Callback successCallback) Measures the view specified by tag relative to the given ancestorTag.
void	measureLayoutRelativeToParent(int tag, Callback errorCallback, Callback successCallback) Like measure(int, com.facebook.react.bridge.Callback) and measureLayout(int, int, com.facebook.react.bridge.Callback, com.facebook.react.bridge.Callback) but measures relative to the immediate parent.
void	onBatchComplete() To implement the transactional requirement mentioned in the class javadoc, we only commit UI changes to the actual view hierarchy once a batch of JS->Java calls have been completed.
void	onCatalystInstanceDestroy() Called before {CatalystInstance#onHostDestroy}
void	onHostDestroy() Called when host (activity/service) receives destroy event (e.g.
void	onHostPause() Called when host (activity/service) receives pause event (e.g.
void	onHostResume() Called when host (activity/service) receives resume event (e.g.
void	registerAnimation(Animation animation) Registers a new Animation that can then be added to a View using addAnimation(int, int, com.facebook.react.bridge.Callback).
void	removeAnimation(int reactTag, int animationID) Removes an existing Animation, canceling it if it was in progress.
void	removeRootView(int rootViewTag)
void	removeSubviewsFromContainerWithID(int containerTag) Method which takes a container tag and then releases all subviews for that container upon receipt.
void	replaceExistingNonRootView(int oldTag, int newTag) Replaces the View specified by oldTag with the View specified by newTag within oldTag's parent.
void	sendAccessibilityEvent(int tag, int eventType)
void	setJSResponder(int reactTag, boolean blockNativeResponder)
void	setLayoutAnimationEnabledExperimental(boolean enabled) LayoutAnimation API on Android is currently experimental.
void	setViewHierarchyUpdateDebugListener(NotThreadSafeViewHierarchyUpdateDebugListener listener)
void	showPopupMenu(int reactTag, ReadableArray items, Callback error, Callback success) Show a PopupMenu.
void	updateView(int tag, java.lang.String className, ReadableMap props)

Methods inherited from class com.facebook.react.bridge.ReactContextBaseJavaModule

getCurrentActivity, getReactApplicationContext

Methods inherited from class com.facebook.react.bridge.BaseJavaModule

canOverrideExistingModule, getMethods, initialize, writeConstantsField

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

UIManagerModule

public UIManagerModule(ReactApplicationContext reactContext,
               java.util.List<ViewManager> viewManagerList,
               UIImplementation uiImplementation)

Method Detail

getName

public java.lang.String getName()

Specified by:

getName in interface NativeModule

Returns:

the name of this module. This will be the name used to require() this module from javascript.

getConstants

public java.util.Map<java.lang.String,java.lang.Object> getConstants()

Overrides:

getConstants in class BaseJavaModule

Returns:

a map of constants this module exports to JS. Supports JSON types.

onHostResume

public void onHostResume()

Description copied from interface: LifecycleEventListener

Called when host (activity/service) receives resume event (e.g. Activity#onResume

Specified by:

onHostResume in interface LifecycleEventListener

onHostPause

public void onHostPause()

Description copied from interface: LifecycleEventListener

Called when host (activity/service) receives pause event (e.g. Activity#onPause

Specified by:

onHostPause in interface LifecycleEventListener

onHostDestroy

public void onHostDestroy()

Description copied from interface: LifecycleEventListener

Called when host (activity/service) receives destroy event (e.g. Activity#onDestroy

Specified by:

onHostDestroy in interface LifecycleEventListener

onCatalystInstanceDestroy

public void onCatalystInstanceDestroy()

Description copied from interface: NativeModule

Called before {CatalystInstance#onHostDestroy}

Specified by:

onCatalystInstanceDestroy in interface NativeModule

Overrides:

onCatalystInstanceDestroy in class BaseJavaModule

addMeasuredRootView

public int addMeasuredRootView(SizeMonitoringFrameLayout rootView)

Registers a new root view. JS can use the returned tag with manageChildren to add/remove children to this view. Note that this must be called after getWidth()/getHeight() actually return something. See CatalystApplicationFragment as an example. TODO(6242243): Make addMeasuredRootView thread safe NB: this method is horribly not-thread-safe, the only reason it works right now is because it's called exactly once and is called before any JS calls are made. As soon as that fact no longer holds, this method will need to be fixed.

removeRootView

public void removeRootView(int rootViewTag)

createView

public void createView(int tag,
              java.lang.String className,
              int rootViewTag,
              ReadableMap props)

updateView

public void updateView(int tag,
              java.lang.String className,
              ReadableMap props)

manageChildren

public void manageChildren(int viewTag,
                  @Nullable
                  ReadableArray moveFrom,
                  @Nullable
                  ReadableArray moveTo,
                  @Nullable
                  ReadableArray addChildTags,
                  @Nullable
                  ReadableArray addAtIndices,
                  @Nullable
                  ReadableArray removeFrom)

Interface for adding/removing/moving views within a parent view from JS.

Parameters:

viewTag - the view tag of the parent view

moveFrom - a list of indices in the parent view to move views from

moveTo - parallel to moveFrom, a list of indices in the parent view to move views to

addChildTags - a list of tags of views to add to the parent

addAtIndices - parallel to addChildTags, a list of indices to insert those children at

removeFrom - a list of indices of views to permanently remove. The memory for the corresponding views and data structures should be reclaimed.

replaceExistingNonRootView

public void replaceExistingNonRootView(int oldTag,
                              int newTag)

Replaces the View specified by oldTag with the View specified by newTag within oldTag's parent. This resolves to a simple manageChildren(int, com.facebook.react.bridge.ReadableArray, com.facebook.react.bridge.ReadableArray, com.facebook.react.bridge.ReadableArray, com.facebook.react.bridge.ReadableArray, com.facebook.react.bridge.ReadableArray) call, but React doesn't have enough info in JS to formulate it itself.

removeSubviewsFromContainerWithID

public void removeSubviewsFromContainerWithID(int containerTag)

Method which takes a container tag and then releases all subviews for that container upon receipt. TODO: The method name is incorrect and will be renamed, #6033872

Parameters:

containerTag - the tag of the container for which the subviews must be removed

measure

public void measure(int reactTag,
           Callback callback)

Determines the location on screen, width, and height of the given view and returns the values via an async callback.

measureLayout

public void measureLayout(int tag,
                 int ancestorTag,
                 Callback errorCallback,
                 Callback successCallback)

Measures the view specified by tag relative to the given ancestorTag. This means that the returned x, y are relative to the origin x, y of the ancestor view. Results are stored in the given outputBuffer. We allow ancestor view and measured view to be the same, in which case the position always will be (0, 0) and method will only measure the view dimensions. NB: Unlike measure(int, com.facebook.react.bridge.Callback), this will measure relative to the view layout, not the visible window which can cause unexpected results when measuring relative to things like ScrollViews that can have offset content on the screen.

measureLayoutRelativeToParent

public void measureLayoutRelativeToParent(int tag,
                                 Callback errorCallback,
                                 Callback successCallback)

Like measure(int, com.facebook.react.bridge.Callback) and measureLayout(int, int, com.facebook.react.bridge.Callback, com.facebook.react.bridge.Callback) but measures relative to the immediate parent. NB: Unlike measure(int, com.facebook.react.bridge.Callback), this will measure relative to the view layout, not the visible window which can cause unexpected results when measuring relative to things like ScrollViews that can have offset content on the screen.

findSubviewIn

public void findSubviewIn(int reactTag,
                 ReadableArray point,
                 Callback callback)

Find the touch target child native view in the supplied root view hierarchy, given a react target location. This method is currently used only by Element Inspector DevTool.

Parameters:

reactTag - the tag of the root view to traverse

point - an array containing both X and Y target location

callback - will be called if with the identified child view react ID, and measurement info. If no view was found, callback will be invoked with no data.

registerAnimation

public void registerAnimation(Animation animation)

Registers a new Animation that can then be added to a View using addAnimation(int, int, com.facebook.react.bridge.Callback).

addAnimation

public void addAnimation(int reactTag,
                int animationID,
                Callback onSuccess)

Adds an Animation previously registered with registerAnimation(com.facebook.react.animation.Animation) to a View and starts it

removeAnimation

public void removeAnimation(int reactTag,
                   int animationID)

Removes an existing Animation, canceling it if it was in progress.

setJSResponder

public void setJSResponder(int reactTag,
                  boolean blockNativeResponder)

clearJSResponder

public void clearJSResponder()

dispatchViewManagerCommand

public void dispatchViewManagerCommand(int reactTag,
                              int commandId,
                              ReadableArray commandArgs)

showPopupMenu

public void showPopupMenu(int reactTag,
                 ReadableArray items,
                 Callback error,
                 Callback success)

Show a PopupMenu.

Parameters:

reactTag - the tag of the anchor view (the PopupMenu is displayed next to this view); this needs to be the tag of a native view (shadow views can not be anchors)

items - the menu items as an array of strings

error - will be called if there is an error displaying the menu

success - will be called with the position of the selected item as the first argument, or no arguments if the menu is dismissed

setLayoutAnimationEnabledExperimental

public void setLayoutAnimationEnabledExperimental(boolean enabled)

LayoutAnimation API on Android is currently experimental. Therefore, it needs to be enabled explicitly in order to avoid regression in existing application written for iOS using this API. Warning : This method will be removed in future version of React Native, and layout animation will be enabled by default, so always check for its existence before invoking it. TODO(9139831) : remove this method once layout animation is fully stable.

Parameters:

enabled - whether layout animation is enabled or not

configureNextLayoutAnimation

public void configureNextLayoutAnimation(ReadableMap config,
                                Callback success,
                                Callback error)

Configure an animation to be used for the native layout changes, and native views creation. The animation will only apply during the current batch operations. TODO(7728153) : animating view deletion is currently not supported. TODO(7613721) : callbacks are not supported, this feature will likely be killed.

Parameters:

config - the configuration of the animation for view addition/removal/update.

success - will be called when the animation completes, or when the animation get interrupted. In this case, callback parameter will be false.

error - will be called if there was an error processing the animation

onBatchComplete

public void onBatchComplete()

To implement the transactional requirement mentioned in the class javadoc, we only commit UI changes to the actual view hierarchy once a batch of JS->Java calls have been completed. We know this is safe because all JS->Java calls that are triggered by a Java->JS call (e.g. the delivery of a touch event or execution of 'renderApplication') end up in a single JS->Java transaction. A better way to do this would be to have JS explicitly signal to this module when a UI transaction is done. Right now, though, this is how iOS does it, and we should probably update the JS and native code and make this change at the same time. TODO(5279396): Make JS UI library explicitly notify the native UI module of the end of a UI transaction using a standard native call

Specified by:

onBatchComplete in interface OnBatchCompleteListener

setViewHierarchyUpdateDebugListener

public void setViewHierarchyUpdateDebugListener(@Nullable
                                       NotThreadSafeViewHierarchyUpdateDebugListener listener)

getEventDispatcher

public EventDispatcher getEventDispatcher()

sendAccessibilityEvent

public void sendAccessibilityEvent(int tag,
                          int eventType)