Cocoa Internals/Widgetset: what changed

Revision 2 to 3. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		## Handles
2	2
3	3		THANDLE - an opaque reference value that's being generated during the .CreateHandle() call of a particular Widgetset class. THANDLE is the value that's used to interface with a control. Using the value a widgetset recognizes a particular control.
4	4
5	5		Most of the Widget interface methods accept TWinControl as a parameter. It's assumed that the Handle property of the control would be used to back reference the actual control. The property stores the value received from the CreateHandle() call made earlier. The HandleAllocated property can be checked in order to know if handle has been previously created or not. If handle has not been created it's expected that the method can fail (returning the proper failure information. Exceptions are not expected?).
6	6
7	7		Overall LCL Handles refer to complex controls. For example, HANDLE can refer to a Memo control that's capable of editing AND scrolling text as needed.
8	8
9	9		Cocoa's composite engine operates controls on a lower level scope. With the Memo example, there's not a single control that does both: text editing and scrolling. Instead there are two separate controls: NSTextView and NSScrollView (both are descendants of NSView). But LCL expects only one value to be returned as a handle.
10	10
11	11		The common rule is the following: the outermost bounds (aka container) control is returned as the handle. Thus in case of Memo, two NSViews are allocated: NSTextView and NSScrollView. But the outermost NSScrollView is returned as theHANDLE. All TCustomMemoWSControl methods are aware of that and treat the handle as such. For example:
12	12
13	13		- if paste action is required, the handle would be used as NSScrollView and then it's documentview would be used to get NSTextView to call forpaste'''.
14	14		- if bounds changes are required (moving, resizing) then the sizes are changed directly for the NSView referenced by HANDLE. (It's assumed that the view would automatically resize its controls. In case of TMemo, NSScrollView would adjust size of NSTextView, if wordwrapping is off).
15	15		- Forms (TForm), that generally correspond to NSWindow, also return their handle as NSView. That view represents the root NSView of a form. However, CocoaWS API's know that and call the necessary NSWindow methods where applicable.
16	16
17	17		HandleViews are stored within Callback object that's being created for each CreateHandle() method.
18	18
19	19		### Handles Reference
20	20
21	21		- Window handle (HWND) is always NSView.
22	22		- TCustomWSForm it is content NSView.
23	23		- Any control that has scroll bars (i.e. TCustomWSList) the it its the embedding NSScrollView (TCocoaScrollView)
24	24
25	25		The table below gives a reference of LCL controls and their implementing classes. Note that the LCL handle returned is not always the same as the implementing class. This applies to controls that have to embedded in a scrollbox.
26	26
27	27		LCL Control
28	28
29	29		WS Part
30	30
31	31		Cocoa Class (NS class)
32	32
33	33		View Returned as LCL Handle
34	34
35	35		Notes
36	36
37	37		TScrollBar
38	38
39	39		Std
40	40
41	41		TCocoaScrollBar (NSScrollBar)
42	42
43	43		self
44	44
45	45		TGroupBox
46	46
47	47		Std
48	48
49	49		TCocoaGroupBox (NSBox)
50	50
51	51		self
52	52
53	53		There's also a content view created to hold all the child controls within the box
54	54
55	55		TComboBox
56	56
57	57		Std
58	58
59	59		TCocoaComboBox (NSComboBox)
60	60
61	61		or
62	62
63	63		TCocoaReadOnlyComboBox (NSPopUpButton)
64	64
65	65		self
66	66
67	67		The actual type is defined by the style of LCL combobox (readonly vs editable)
68	68
69	69		TListBox
70	70
71	71		Std
72	72
73	73		TCocoaTableView (NSTableView)
74	74
75	75		NSScrollView
76	76
77	77		The behavior of TListbox is defined by the callback object TLCLListBoxCallback assigned to TCocoaTableView.
78	78
79	79		TEdit
80	80
81	81		Std
82	82
83	83		TCocoaTextField (NSTextField)
84	84
85	85		self
86	86
87	87		TCocoaTextField itself is readonly static field. The editing capabilities are implemented by TCocoaFieldEditor, which is driven by AppKit "editing" schema
88	88
89	89		TMemo
90	90
91	91		Std
92	92
93	93		TCocoaTextView (NSTextView)
94	94
95	95		NSScrollView
96	96
97	97		Lines property is implemented via TCocoaMemoStrings
98	98
99	99		TButton
100	100
101	101		Std
102	102
103	103		TCocoaButton (NSButton)
104	104
105	105		self
106	106
107	107		TCheckBox
108	108
109	109		Std
110	110
111	111		TCocoaButton (NSButton)
112	112
113	113		self
114	114
115	115		Checkbox is still a button but with a different Bezel
116	116
117	117		TToggleBox
118	118
119	119		Std
120	120
121	121		TCocoaButton (NSButton)
122	122
123	123		self
124	124
125	125		TRadioButton
126	126
127	127		Std
128	128
129	129		TCocoaButton (NSButton)
130	130
131	131		self
132	132
133	133		Radiobutton is still a button but with a different Bezel
134	134
135	135		TStaticText
136	136
137	137		Std
138	138
139	139		TCocoaTextField (NSTextField)
140	140
141	141		self
142	142
143	143		This field doesn't allow editor to be enabled
144	144
145	145		[[TTrackBar]]
146	146
147	147		Com
148	148
149	149		[[Cocoa Internals/Buttons\|TCocoaSlider]] (NSSlider)
150	150
151	151		self
152	152
153	153		## Focusing
154	154
155	155		That has important impact of FOCUS-ing. Cocoa doesn't operate the term "focused" instead it's using terms "firstRepsonder" and "key" view/window. Generally focused control corresponds to Cocoa's "firstResponder". The NSResponder object (typically NSView) is the first object that would handle key or mouse events. However, this is not the case for composed controls. TMemo is a combination of NSScrollView and NSTextField. NSScrollView is used as a handle. If, NSTextField would be the firstRepsonder, CocoaWS needs to return NSScrollView as focused HANDLE.
156	156
157	157		The same approach is applicable in reverse. If SetFocus is made for the HANDLE that represents NSScrollView with NSTextField inside. NSTextField should actually become Cocoa's firstResponder.
158	158
159	159		The expected order of events is:
160	160
161	161		- LM_KILLFOCUS
162	162		- LM_SETFOCUS
163	163
164	164		Note that unlike WinAPI WM_KILLFOCUS, LM_KILLFOCUS doesn't provide the information about "the next suggested" control to be focused. For controls that have some sort of editors (i.e. TTreeView with a node editor (TEdit) active) such approach is causing to switch focus to TForm (the hosting form), for the next focus control selection.
165	165
166	166		The focus switch notification is handled in TCocoaWindow makeFirstResponder call. Due to problems with the recursive calls of changing the focus, the current order of events is:
167	167
168	168		- LM_SETFOCUS
169	169		- LM_KILLFOCUS
170	170
171	171		(for Cocoa WS)
172	172
173	173		#### Need of Window
174	174
175	175		The "firstResponder" is a property of a window. Thus a view can become a "firstResponder" only if it's within NSWindow's view hierarchy. This is important for complex controls, such as a TabControl. It manages multiple child views (each view for a tab). Only one view is visible at a time. All over views are actually DETACHED from NSWindow hierarchy. (while from LCL perspective they are still children of TForm). When switching between tabs a notification about a successful switch should only be delivered when a new view is in the Window hierarchy.
176	176
177	177		#### Ignoring System Setting
178	178
179	179		LCL basic logic is to focus every control that is a tab stoppable (which is every TWinControl by default) user. Where in macOS there's a system setting of Full Keyboard Access (which is off by default). If the setting is off then macOS acts similar to what LCL does. If it's on only "keyboard input" controls are "tab-reachable" text fields (including editable combo-boxes) and lists. Buttons, scrollers are skipped from tabbing. LCL doesn't currently support limited tabbing.
180	180
181	181		#### Focus Ring
182	182
183	183		Focus Ring is not drawn for controls with BorderStyle set to bsNone. (that allows to visually "hide" controls)
184	184
185	185		If global variable CocoaHideFocusNoBorder is set to false, then the focus remains unchanged.
186	186
187	187		## Cursors
188	188
189	189		Widgetset cursors are based on NSCursor class. Which very nice and convenient to use. Cocoa however, doesn't provide some of the cursors that do exist in windows/LCL. For example: diagonal resize. Diagonal cursors are generated by rotation of the horizontal cursors.
190	190
191	191		## User Prompts and Modal Dialogs
192	192
193	193		Most of the dialogs are based on NSModal class.
194	194
195	195		With the switch of rendering engine to layered drawing (effective macOS 10.14), an attempt to show a modal dialog during rendering (or any other stage of animation. I.e. "Activation") would cause an exception:
196	196
197		-	~~`Application Specific Information:`\~~
198		-	~~`*** Terminating app due to uncaught exception 'NSGenericException', reason: '-[NSAlert runModal]`\~~
199		-	~~`may not be invoked inside of transaction begin/commit pair, or inside of transaction commit `\~~
200		-	~~`(usually this means it was invoked inside of a view's -drawRect: method.)'`~~
	197	+	``` pascal
	198	+	Application Specific Information:
	199	+	*** Terminating app due to uncaught exception 'NSGenericException', reason: '-[NSAlert runModal]
	200	+	may not be invoked inside of transaction begin/commit pair, or inside of transaction commit
	201	+	(usually this means it was invoked inside of a view's -drawRect: method.)'
	202	+	```
201	203
202	204		However, if the error dialog is shown as a "sheet" then the error doesn't occur.
203	205
204	206		## See Also
205	207
206	208		- [[Cocoa Internals]]
207	209
208	210		---
209	211		From the Free Pascal wiki, page "Cocoa Internals/Widgetset", as it stood on 2020-10-05 after a change by Trev, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
210	212		Category: Cocoa
211	213		Category: macOS

Back to history