Cocoa Internals/Extensions: what changed
Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.
| Old | New | Line | |
|---|---|---|---|
| 1 | 1 | Extensions are used to add additional lcl-friendly methods to all Cocoa classes. The default implementation of each method should: | |
| 2 | 2 | ||
| 3 | 3 | - either indicate that a class is not a LCL-specific class (it's Cocoa native) thus should be handled with care | |
| 4 | 4 | - provide a basic functionality for LCL types (for example setting a control bounds using TRect type. Where cocoa is using float-point NSRect) | |
| 5 | 5 | ||
| 6 | 6 | ## Extensions | |
| 7 | 7 | ||
| 8 | 8 | ### LCLObjectExtension | |
| 9 | 9 | ||
| 10 | 10 | The extensions adds additional methods to **NSObject** class of cocoa. (This is TObject counterpart, where (almost) all classes in Cocoa inherit from). | |
| 11 | 11 | ||
| 12 | 12 | A lot of the methods below are control specific methods, thus it might be a good idea to elevate the extension from NSObject to NSView or NSControl. However, this might impact other control-like objects (i.w. NSWindow?) | |
| 13 | 13 | ||
| 14 | 14 | #### Methods | |
| 15 | 15 | ||
| 16 | - | ||
| 17 | - | ||
| 18 | - | ||
| 19 | - | ||
| 20 | - | ||
| 21 | - | ||
| 22 | - | ||
| 23 | - | ||
| 24 | - | ||
| 25 | - | ||
| 26 | - | ||
| 27 | - | ||
| 28 | - | ||
| 29 | - | ||
| 30 | - | ||
| 31 | - | ||
| 32 | - | ||
| 33 | - | ||
| 34 | - | ||
| 35 | - | ||
| 36 | - | ||
| 37 | - | ||
| 38 | - | ||
| 39 | - | ||
| 40 | - | ||
| 41 | - | ||
| 42 | - | ||
| 43 | - | ||
| 44 | - | ||
| 45 | - | ||
| 46 | - | ||
| 47 | - | ||
| 48 | - | ||
| 49 | - | ||
| 50 | - | ||
| 51 | - | ||
| 52 | - | ||
| 53 | - | ||
| 54 | - | ||
| 55 | - | ||
| 56 | - | ||
| 57 | - | ||
| 58 | - | ||
| 59 | - | ||
| 60 | - | ||
| 61 | - | ||
| 62 | - | ||
| 63 | - | ||
| 64 | - | ||
| 65 | - | ||
| 66 | - | ||
| 67 | - | ||
| 68 | - | ||
| 69 | - | ||
| 70 | - | ||
| 71 | - | ||
| 72 | - | ||
| 73 | - | ||
| 74 | - | ||
| 75 | - | ||
| 76 | - | ||
| 77 | - | ||
| 78 | - | ||
| 79 | - | ||
| 80 | - | ||
| 81 | - | ||
| 82 | - | ||
| 83 | - | ||
| 84 | - | ||
| 85 | - | ||
| 86 | - | ||
| 87 | - | ||
| 88 | - | ||
| 89 | - | ||
| 90 | - | ||
| 91 | - | ||
| 92 | - | ||
| 93 | - | ||
| 94 | - | ||
| 95 | - | ||
| 96 | - | ||
| 97 | - | ||
| 98 | - | ||
| 99 | - | ||
| 100 | - | ||
| 101 | - | ||
| 102 | - | ||
| 103 | - | ||
| 104 | - | ||
| 16 | + | **Method** | |
| 17 | + | ||
| 18 | + | **Description** | |
| 19 | + | ||
| 20 | + | **Default behavior** | |
| 21 | + | ||
| 22 | + | LCLObjectExtension | |
| 23 | + | ||
| 24 | + | LCLViewExtensions | |
| 25 | + | ||
| 26 | + | lclIsEnabled | |
| 27 | + | ||
| 28 | + | Returns true/false if control is enabled | |
| 29 | + | ||
| 30 | + | false | |
| 31 | + | ||
| 32 | + | true | |
| 33 | + | ||
| 34 | + | lclSetEnable | |
| 35 | + | ||
| 36 | + | Enables or disables the control | |
| 37 | + | ||
| 38 | + | does nothing | |
| 39 | + | ||
| 40 | + | traverses child views and passes new enabled status to them | |
| 41 | + | ||
| 42 | + | lclisVisible | |
| 43 | + | ||
| 44 | + | Returns true/false if control is visible | |
| 45 | + | ||
| 46 | + | false | |
| 47 | + | ||
| 48 | + | not [hidden()](https://developer.apple.com/documentation/appkit/nsview/1483369-hidden) | |
| 49 | + | ||
| 50 | + | lclSetVisible | |
| 51 | + | ||
| 52 | + | shows or hides a control | |
| 53 | + | ||
| 54 | + | does nothing | |
| 55 | + | ||
| 56 | + | setHidden() (where is the method in the documentation? deprecated?) | |
| 57 | + | ||
| 58 | + | lclisHandle | |
| 59 | + | ||
| 60 | + | Returns true if the instance of the class can be considered a LCL handle | |
| 61 | + | ||
| 62 | + | false | |
| 63 | + | ||
| 64 | + | lclClientFrame | |
| 65 | + | ||
| 66 | + | Returns client rectangle (content of the control) in the control's coordinate system | |
| 67 | + | ||
| 68 | + | does nothing | |
| 69 | + | ||
| 70 | + | lclFrame | |
| 71 | + | ||
| 72 | + | Returns controls position rectangle in the parent's coordinate system | |
| 73 | + | ||
| 74 | + | does nothing | |
| 75 | + | ||
| 76 | + | frame() | |
| 77 | + | ||
| 78 | + | lclContentView | |
| 79 | + | ||
| 80 | + | Returns NSView that represents the (drawn) contents. In many NSViews or combination of NSViews the content might be different. For example for NSButton (TButton), the content view is NSButton itself. For NSBox (TGroupBox), the content view is contentView. For a NSTextView sunken in NSScrollView (TMemo) the contentView would be documentView of NSScrollView. | |
| 81 | + | ||
| 82 | + | **Important**: lclContentView is also a view where all children controls should be added-to. | |
| 83 | + | ||
| 84 | + | **Important**: lclContentView is also a view that should receive focus (become a firstReponder) | |
| 85 | + | ||
| 86 | + | The problem is that all WidgetAPI calls are made through a control Handle. Handle doesn't always map to a NSView directly (TMemo, TGroupbox) where additional NSViews are in placed. lclContentView is intent to return the view, where the **draw** methods are called. The method is used by lclInvalidate and lclInvaldateRect. | |
| 87 | + | ||
| 88 | + | It should be overridden in every composite component to return the actual drawn contents. | |
| 89 | + | ||
| 90 | + | **The alternative** to not having this method is to override lclInvalidateRect for each composition control (which is also doable) | |
| 91 | + | ||
| 92 | + | nil | |
| 93 | + | ||
| 94 | + | returns self | |
| 95 | + | ||
| 96 | + | lclGetCallback | |
| 97 | + | ||
| 98 | + | The method would only be implemented by LCL controls that inherited from Cocoa controls and are used as LCL widgets. (i.e. TCocoaButton) | |
| 99 | + | ||
| 100 | + | The method returns the callback interface that was allocated during LCL Handle creation. ObjC control is responsible for storing the interfaces in some manner. (typically a field is added to a subclass). | |
| 101 | + | ||
| 102 | + | Note that the returned callback can be nil, in two cases: | |
| 103 | + | ||
| 104 | + | 1\) the ObjC object queried is NOT an LCL created object | |
| 105 | + | ||
| 106 | + | 2\) the ObjC object is being destroyed (by LCL DestroyHandel call), and thus the callback has already been cleared | |
| 107 | + | ||
| 108 | + | nil | |
| 109 | + | ||
| 110 | + | nil | |
| 111 | + | ||
| 112 | + | lclClearCallback | |
| 113 | + | ||
| 114 | + | The method should be implemented by LCL controls used as widgets. | |
| 115 | + | ||
| 116 | + | The method clears out the callback interface. Meaning that a subsequent call of lclGetCallback should return nil. The object should also clear out the internal reference. Any methods that are using callback interface (to report events) must always check, if the callback has not been cleared yet. | |
| 117 | + | ||
| 118 | + | It's not uncommon to destroy the object, that started an event. (i.e. freeing control, during MouseUp or MouseDown). | |
| 119 | + | ||
| 120 | + | Thus LCL provides it's own kind of protection. The widgetset is expecting itself NOT to cause a conflict (i.e. should not return any event from a handle, that has already been destroyed) | |
| 121 | + | ||
| 122 | + | does nothing | |
| 123 | + | ||
| 124 | + | does nothing. | |
| 105 | 125 | ||
| 106 | 126 | **Consideration**: if everything is bound to lclContentView. - why is it not used as a Handle anyway? Because Handle needs to match the hierarchy of Cocoa objects. I.e. an actual content residers within a ScrollView. And ScrollView is am immediate child of Form. Not the its contents. | |
| 107 | 127 | ||
| 108 | 128 | ### Convention | |
| 109 | 129 | ||
| 110 | 130 | - All lcl extension methods should start with "lcl" to distinguish them Cocoa native methods. | |
| 111 | 131 | ||
| 112 | 132 | ## Enabled State | |
| 113 | 133 | ||
| 114 | 134 | Enabled state is a basic attribute of all Controls in LCL. | |
| 115 | 135 | ||
| 116 | 136 | In Cocoa Enabled state is only part of NSControl class (derived). Not every LCL-control is mapped to Cocoa NSControl. For example TGroupBox is mapped to NSBox in Cocoa. NSBox is a subclass of NSView (and not NSControl). Thus NSBox doesn't have methods to control if it's enabled or not. (NSBox cannot be "disabled") | |
| 117 | 137 | ||
| 118 | 138 | In order to treat all Cocoa classes the same, LCLExtension introduced 2 methods lclIsEnabled and lclSetEnabled. | |
| 119 | 139 | ||
| 120 | 140 | - for subclasses of NSControl these methods are almost direct mapping to **setEnabled** and **enabled** methods. | |
| 121 | 141 | - for NSView, NSWindow the implementation may vary | |
| 122 | 142 | ||
| 123 | 143 | ### Switching Enabled State for Children | |
| 124 | 144 | ||
| 125 | 145 | In LCL design, once a parent control has been disabled, all it's children are disabled automatically. (Yet, they keep their "Enabled" property) | |
| 126 | 146 | ||
| 127 | 147 | If a parent control has been enabled, then all its children are changing to the state of their "Enabled" property. | |
| 128 | 148 | ||
| 129 | 149 | Traversing children must be done implicitly within Widgetset itself. (There's no LCL code to pass through children and change the state). | |
| 130 | 150 | ||
| 131 | 151 | Cocoa implements the loop of state change in LCLViewExtension for **lclSetEnabled** method. | |
| 132 | 152 | ||
| 133 | 153 | **ICommonCallBack** provides a method GetShouldBeEnabled, that returns **Enabled** property of a mapped LCL control. Used whenever a lclSetEnabled is requested to enable controls. | |
| 134 | 154 | ||
| 135 | 155 | ## See Also | |
| 136 | 156 | ||
| 137 | 157 | - [[Cocoa Internals]] | |
| 138 | 158 | ||
| 139 | 159 | --- | |
| 140 | 160 | *From the Free Pascal wiki, page "Cocoa Internals/Extensions", as it stood on 2019-12-29 after a change by Skalogryz, 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).* | |
| 141 | 161 | Category: Cocoa | |
| 142 | 162 | Category: macOS |