Skip to content

Commit 8d8c6a3

Browse files
CopilotSaadnajmi
Copilot
and
Saadnajmi
committed
Add macOS-specific View props and events documentation pages
Co-authored-by: Saadnajmi <[email protected]>
1 parent 200cfd8 commit 8d8c6a3

File tree

3 files changed

+480
-0
lines changed

3 files changed

+480
-0
lines changed

‎docsite/docs/api-reference/_category_.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"label": "API Reference",
3+
"position": 4,
4+
"link": {
5+
"type": "generated-index",
6+
"description": "API reference for macOS-specific props and events in React Native macOS."
7+
},
8+
"collapsed": false
9+
}

‎docsite/docs/api-reference/view-events.md‎

Lines changed: 294 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,294 @@
1+
---
2+
sidebar_label: 'View Events (macOS)'
3+
sidebar_position: 2
4+
---
5+
6+
# View Events (macOS)
7+
8+
React Native macOS extends the standard React Native View component with additional events that are specific to macOS. These events allow you to respond to macOS-specific user interactions such as keyboard input, mouse movements, drag and drop operations, and more.
9+
10+
## Events
11+
12+
### `onBlur`
13+
14+
Fired when the view loses focus.
15+
16+
**Event Data:** Standard focus event
17+
18+
This event is useful for implementing custom focus management and validation logic when a view loses keyboard focus.
19+
20+
---
21+
22+
### `onDoubleClick`
23+
24+
Fired when the user double-clicks on the view.
25+
26+
**Event Data:** Mouse event with the following properties:
27+
- `clientX`: Horizontal position in the target view
28+
- `clientY`: Vertical position in the target view
29+
- `screenX`: Horizontal position in the window
30+
- `screenY`: Vertical position in the window
31+
- `altKey`: Whether Alt/Option key is pressed
32+
- `ctrlKey`: Whether Control key is pressed
33+
- `shiftKey`: Whether Shift key is pressed
34+
- `metaKey`: Whether Command key is pressed
35+
36+
Example:
37+
```javascript
38+
<View onDoubleClick={(event) => {
39+
console.log('Double clicked at', event.nativeEvent.clientX, event.nativeEvent.clientY);
40+
}}>
41+
<Text>Double click me</Text>
42+
</View>
43+
```
44+
45+
---
46+
47+
### `onDragEnter`
48+
49+
Fired when a drag operation enters the view's bounds.
50+
51+
**Event Data:** Drag event with mouse position and data transfer information
52+
53+
This event is fired when the user drags content over the view. Use this to provide visual feedback that the view can accept the dragged content.
54+
55+
---
56+
57+
### `onDragLeave`
58+
59+
Fired when a drag operation leaves the view's bounds.
60+
61+
**Event Data:** Drag event with mouse position and data transfer information
62+
63+
This event is fired when the user drags content away from the view. Use this to remove any visual feedback shown during drag enter.
64+
65+
---
66+
67+
### `onDrop`
68+
69+
Fired when the user drops content onto the view.
70+
71+
**Event Data:** Drag event with the following properties:
72+
- Mouse position (`clientX`, `clientY`, `screenX`, `screenY`)
73+
- Modifier keys (`altKey`, `ctrlKey`, `shiftKey`, `metaKey`)
74+
- `dataTransfer`: Object containing:
75+
- `files`: Array of dropped files, each with:
76+
- `name`: File name
77+
- `type`: MIME type
78+
- `uri`: File URI
79+
- `size`: File size (optional)
80+
- `width`: Image width (optional, for images)
81+
- `height`: Image height (optional, for images)
82+
- `items`: Array of data transfer items, each with:
83+
- `kind`: Item kind (e.g., 'file', 'string')
84+
- `type`: MIME type
85+
- `types`: Array of available data types
86+
87+
Example:
88+
```javascript
89+
<View
90+
draggedTypes={['public.file-url']}
91+
onDrop={(event) => {
92+
const files = event.nativeEvent.dataTransfer.files;
93+
files.forEach(file => {
94+
console.log('Dropped file:', file.name, file.uri);
95+
});
96+
}}
97+
>
98+
<Text>Drop files here</Text>
99+
</View>
100+
```
101+
102+
---
103+
104+
### `onFocus`
105+
106+
Fired when the view receives focus.
107+
108+
**Event Data:** Standard focus event
109+
110+
This event is useful for implementing custom focus management and showing focus-specific UI elements.
111+
112+
---
113+
114+
### `onKeyDown`
115+
116+
Fired when a key is pressed while the view has focus.
117+
118+
**Event Data:** Key event with the following properties:
119+
- `key`: The key value (aligned with [W3C UI Events](https://www.w3.org/TR/uievents-key/))
120+
- `altKey`: Whether Alt/Option key is pressed
121+
- `ctrlKey`: Whether Control key is pressed
122+
- `shiftKey`: Whether Shift key is pressed
123+
- `metaKey`: Whether Command key is pressed
124+
- `capsLockKey`: Whether Caps Lock is active
125+
- `numericPadKey`: Whether the key is on the numeric keypad
126+
- `helpKey`: Whether Help key is pressed
127+
- `functionKey`: Whether a function key is pressed
128+
129+
:::note
130+
To receive key events, the view must have `focusable={true}` set, and you should specify which keys to handle using the `keyDownEvents` prop.
131+
:::
132+
133+
Example:
134+
```javascript
135+
<View
136+
focusable={true}
137+
keyDownEvents={[
138+
{ key: 'Enter' },
139+
{ key: 's', metaKey: true }
140+
]}
141+
onKeyDown={(event) => {
142+
const { key, metaKey } = event.nativeEvent;
143+
if (key === 'Enter') {
144+
console.log('Enter pressed');
145+
} else if (key === 's' && metaKey) {
146+
console.log('Command+S pressed');
147+
}
148+
}}
149+
>
150+
<Text>Press Enter or Cmd+S</Text>
151+
</View>
152+
```
153+
154+
---
155+
156+
### `onKeyUp`
157+
158+
Fired when a key is released while the view has focus.
159+
160+
**Event Data:** Key event (same format as `onKeyDown`)
161+
162+
:::note
163+
To receive key events, the view must have `focusable={true}` set, and you should specify which keys to handle using the `keyUpEvents` prop.
164+
:::
165+
166+
---
167+
168+
### `onMouseEnter`
169+
170+
Fired when the mouse cursor enters the view's bounds.
171+
172+
**Event Data:** Mouse event with the following properties:
173+
- `clientX`: Horizontal position in the target view
174+
- `clientY`: Vertical position in the target view
175+
- `screenX`: Horizontal position in the window
176+
- `screenY`: Vertical position in the window
177+
- `altKey`: Whether Alt/Option key is pressed
178+
- `ctrlKey`: Whether Control key is pressed
179+
- `shiftKey`: Whether Shift key is pressed
180+
- `metaKey`: Whether Command key is pressed
181+
182+
Example:
183+
```javascript
184+
<View onMouseEnter={(event) => {
185+
console.log('Mouse entered at', event.nativeEvent.clientX, event.nativeEvent.clientY);
186+
}}>
187+
<Text>Hover over me</Text>
188+
</View>
189+
```
190+
191+
---
192+
193+
### `onMouseLeave`
194+
195+
Fired when the mouse cursor leaves the view's bounds.
196+
197+
**Event Data:** Mouse event (same format as `onMouseEnter`)
198+
199+
Example:
200+
```javascript
201+
<View
202+
onMouseEnter={() => setIsHovered(true)}
203+
onMouseLeave={() => setIsHovered(false)}
204+
style={{ backgroundColor: isHovered ? 'lightblue' : 'white' }}
205+
>
206+
<Text>Hover state example</Text>
207+
</View>
208+
```
209+
210+
---
211+
212+
## Complete Example
213+
214+
Here's a comprehensive example showing multiple macOS-specific events:
215+
216+
```javascript
217+
import React, { useState } from 'react';
218+
import { View, Text, StyleSheet } from 'react-native';
219+
220+
function MacOSEventsExample() {
221+
const [status, setStatus] = useState('Ready');
222+
const [isHovered, setIsHovered] = useState(false);
223+
224+
return (
225+
<View style={styles.container}>
226+
<View
227+
style={[
228+
styles.interactiveView,
229+
isHovered && styles.hoveredView
230+
]}
231+
focusable={true}
232+
enableFocusRing={true}
233+
draggedTypes={['public.file-url', 'public.text']}
234+
keyDownEvents={[
235+
{ key: 'Enter' },
236+
{ key: 'Escape' }
237+
]}
238+
onFocus={() => setStatus('Focused')}
239+
onBlur={() => setStatus('Blurred')}
240+
onKeyDown={(e) => setStatus(`Key down: ${e.nativeEvent.key}`)}
241+
onKeyUp={(e) => setStatus(`Key up: ${e.nativeEvent.key}`)}
242+
onMouseEnter={(e) => {
243+
setIsHovered(true);
244+
setStatus(`Mouse entered at (${e.nativeEvent.clientX}, ${e.nativeEvent.clientY})`);
245+
}}
246+
onMouseLeave={() => {
247+
setIsHovered(false);
248+
setStatus('Mouse left');
249+
}}
250+
onDoubleClick={() => setStatus('Double clicked!')}
251+
onDragEnter={() => setStatus('Drag entered')}
252+
onDragLeave={() => setStatus('Drag left')}
253+
onDrop={(e) => {
254+
const files = e.nativeEvent.dataTransfer.files;
255+
setStatus(`Dropped ${files.length} file(s)`);
256+
}}
257+
>
258+
<Text>Interactive macOS View</Text>
259+
<Text style={styles.statusText}>{status}</Text>
260+
</View>
261+
</View>
262+
);
263+
}
264+
265+
const styles = StyleSheet.create({
266+
container: {
267+
flex: 1,
268+
justifyContent: 'center',
269+
alignItems: 'center',
270+
},
271+
interactiveView: {
272+
width: 300,
273+
height: 200,
274+
backgroundColor: 'white',
275+
borderWidth: 2,
276+
borderColor: 'gray',
277+
padding: 20,
278+
},
279+
hoveredView: {
280+
backgroundColor: 'lightblue',
281+
},
282+
statusText: {
283+
marginTop: 10,
284+
fontStyle: 'italic',
285+
},
286+
});
287+
288+
export default MacOSEventsExample;
289+
```
290+
291+
## See Also
292+
293+
- [View Props (macOS)](./view-props.md) - macOS-specific props for View components
294+
- [React Native View Component](https://reactnative.dev/docs/view) - Base View component documentation

0 commit comments

Comments
 (0)