useFocus

The useFocus hook provides business logic for changing the pan offset and zoom values in order to focus on specific areas of the viewport. It returns three functions: focusDesignArea, focusRegion, and focusItem.

focusDesignArea takes two arguments: the id of the panel to focus, and an optional options object with the following interface:

name	type	required	comment
animateOnPan	boolean	no	If true, set the LayoutStore's isTransitioning value to true.
changeZoom	boolean	no	Whether or not to actually change the zoom value when focusing. Default value: true

Generally, focusDesignArea can be called when the experience loads, since the default zoom and pan values aren't likely to be useful.

focusRegion takes three arguments: The panelId within which to focus, a box with an x, y, width, and height that defines the region to be focused, and an optional options object with the following interface:

name	type	required	comment
animateOnPan	boolean	no	If true, set the LayoutStore's isTransitioning value to true.
changeZoom	boolean	no	Whether or not to actually change the zoom value when focusing. Default value: true
margins	Margins	no	An object with top, left, right, and bottom, in pixels. Used to provide more space around the focused area.
restrictToPanelBoundary	boolean	no	If the area requested to be focused is larger than the panel in some dimension, then constrain on the dimensions of the panel. Default value: true

Lastly, focusItem takes two arguments: The id of the item to focus, and the same options object as focusRegion.

Check out the interactive demo below the example code block.

const FocusControls = observer(() => {
    const { focusDesignArea, focusItem } = useFocus();
    const designEngine = useDesignEngine();
    const { panContainer } = useLayoutContainers();
    const idaStore = designEngine.idaStore;

    useEffect(() => {
        if (panContainer) {
            // Focus the first panel when the design starts
            focusDesignArea(designEngine.cimDocStore.panels[0].id);
        }
    }, [panContainer]);

    const selectedId = idaStore.selectedIds.size === 1 ? [...idaStore.selectedIds.values()][0] : undefined;

    return (
        <div>
            <div>
                <button onClick={() => focusDesignArea(designEngine.cimDocStore.panels[0].id)}>
                    Focus first panel
                </button>
                <button onClick={() => focusDesignArea(designEngine.cimDocStore.panels[1].id)}>
                    Focus second panel
                </button>
                <button
                    onClick={() => {
                        if (selectedId) {
                            focusItem(selectedId, { margins: { top: 10, left: 10, right: 10, bottom: 10 } });
                        }
                    }}
                    disabled={idaStore.selectedIds.size !== 1}
                >
                    Focus selected item
                </button>
            </div>
        </div>
    );
});