Skip to content

Commit 1736d8f

Browse files
gcasagcasa
committed
Add new documentation
1 parent 6fd7524 commit 1736d8f

File tree

2 files changed

+151
-5
lines changed

2 files changed

+151
-5
lines changed

‎Headers/AppKit/NSNibConnector.h‎

Lines changed: 120 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
1-
/*
1+
/*
22
NSNibConnector.h
33
44
Copyright (C) 1999 Free Software Foundation, Inc.
55
66
Author: Richard Frith-Macdonald <[email protected]>
77
Date: 1999
8-
8+
99
This file is part of the GNUstep GUI Library.
1010
1111
This library is free software; you can redistribute it and/or
@@ -20,10 +20,10 @@
2020
2121
You should have received a copy of the GNU Lesser General Public
2222
License along with this library; see the file COPYING.LIB.
23-
If not, see <http://www.gnu.org/licenses/> or write to the
24-
Free Software Foundation, 51 Franklin Street, Fifth Floor,
23+
If not, see <http://www.gnu.org/licenses/> or write to the
24+
Free Software Foundation, 51 Franklin Street, Fifth Floor,
2525
Boston, MA 02110-1301, USA.
26-
*/
26+
*/
2727

2828
#ifndef _GNUstep_H_NSNibConnector
2929
#define _GNUstep_H_NSNibConnector
@@ -34,20 +34,135 @@
3434
@class NSString;
3535

3636
APPKIT_EXPORT_CLASS
37+
/**
38+
* NSNibConnector is the abstract base class for objects that represent
39+
* connections between user interface elements and their controllers in
40+
* Interface Builder nib files. This class provides the fundamental
41+
* infrastructure for establishing relationships between objects during
42+
* nib loading and instantiation. Connectors maintain references to source
43+
* and destination objects along with identifying labels that specify the
44+
* nature of the connection. The class supports the declarative interface
45+
* paradigm by storing connection metadata that is processed at runtime
46+
* to establish actual object relationships. Subclasses like NSNibOutletConnector
47+
* and NSNibControlConnector provide specific implementations for different
48+
* types of connections such as outlet bindings and action-target relationships.
49+
* The connector system enables visual interface design tools to create
50+
* complex object interconnections that are automatically established when
51+
* nib files are loaded, bridging the gap between design-time declarations
52+
* and runtime object behavior.
53+
*/
3754
@interface NSNibConnector : NSObject <NSCoding>
3855
{
3956
id _src;
4057
id _dst;
4158
NSString *_tag;
4259
}
4360

61+
/**
62+
* Returns the destination object of this connector. The destination object
63+
* represents the target end of the connection relationship, typically the
64+
* object that will receive messages or be assigned to properties during
65+
* connection establishment. For outlet connections, the destination is
66+
* usually a user interface element that will be referenced by the source
67+
* object. For action connections, the destination is the object that will
68+
* receive action messages from user interface controls. The destination
69+
* object is established during nib loading when objects are instantiated
70+
* and their relationships are resolved. This method provides access to
71+
* the destination for connection processing and relationship management.
72+
*/
4473
- (id) destination;
74+
/**
75+
* Establishes the actual connection between the source and destination
76+
* objects according to the connector's configuration. This abstract method
77+
* must be overridden by subclasses to provide specific connection behavior
78+
* appropriate for their connection type. The connection establishment process
79+
* typically occurs during nib loading after all objects have been instantiated
80+
* and are ready for interconnection. For outlet connectors, this might involve
81+
* setting instance variables or properties using key-value coding. For action
82+
* connectors, this might involve configuring target-action relationships on
83+
* user interface controls. The method coordinates the final step in the
84+
* declarative connection process defined in Interface Builder.
85+
*/
4586
- (void) establishConnection;
87+
/**
88+
* Returns the label string that identifies this connector's connection type
89+
* or target property. The label typically corresponds to the name of an
90+
* outlet, action, or other connection identifier that was specified in
91+
* Interface Builder during the visual connection process. For outlet
92+
* connections, the label usually matches the name of an instance variable
93+
* or property on the source object. For action connections, the label
94+
* typically corresponds to an action method name. This identifier is used
95+
* during connection establishment to determine the specific connection
96+
* behavior and target location for the relationship. The label provides
97+
* the semantic meaning that transforms generic source-destination relationships
98+
* into specific functional connections.
99+
*/
46100
- (NSString*) label;
101+
/**
102+
* Replaces references to one object with another object within this connector's
103+
* configuration. This method is used during nib loading when object references
104+
* need to be updated, typically when placeholder objects are replaced with
105+
* actual instances or when object identity changes during the instantiation
106+
* process. The anObject parameter specifies the object to be replaced, while
107+
* anotherObject specifies the replacement object. The connector updates its
108+
* internal references to maintain correct connection relationships even when
109+
* object identities change during nib loading. This mechanism ensures that
110+
* connections remain valid throughout the complex object instantiation and
111+
* replacement processes that occur during nib file processing.
112+
*/
47113
- (void) replaceObject: (id)anObject withObject: (id)anotherObject;
114+
/**
115+
* Returns the source object of this connector. The source object represents
116+
* the originating end of the connection relationship, typically the object
117+
* that will contain references to other objects or initiate communication.
118+
* For outlet connections, the source is usually a controller object that
119+
* will maintain references to user interface elements. For action connections,
120+
* the source is typically a user interface control that will send action
121+
* messages to target objects. The source object is established during nib
122+
* loading when objects are instantiated and their relationships are resolved.
123+
* This method provides access to the source object for connection processing
124+
* and relationship management during the nib loading process.
125+
*/
48126
- (id) source;
127+
/**
128+
* Sets the destination object for this connector. The anObject parameter
129+
* specifies the target object that will serve as the destination end of
130+
* the connection relationship. This method is typically called during nib
131+
* loading when objects are being instantiated and connections are being
132+
* configured. The destination object represents the target of the connection,
133+
* which might be a user interface element for outlet connections or a
134+
* controller object for action connections. Setting the destination establishes
135+
* one half of the connection relationship that will be completed when the
136+
* connection is established. The destination must be compatible with the
137+
* connection type and the requirements of the source object.
138+
*/
49139
- (void) setDestination: (id)anObject;
140+
/**
141+
* Sets the label string that identifies this connector's connection type
142+
* or target property. The label parameter specifies the connection identifier
143+
* that corresponds to outlet names, action method names, or other connection
144+
* semantics defined in Interface Builder. This label is used during connection
145+
* establishment to determine the specific behavior and target for the
146+
* relationship. For outlet connections, the label typically matches an
147+
* instance variable or property name on the source object. For action
148+
* connections, the label usually corresponds to an action method signature.
149+
* Setting the appropriate label ensures that the connector can establish
150+
* the correct type of connection with the proper semantic meaning during
151+
* nib loading.
152+
*/
50153
- (void) setLabel: (NSString*)label;
154+
/**
155+
* Sets the source object for this connector. The anObject parameter specifies
156+
* the originating object that will serve as the source end of the connection
157+
* relationship. This method is typically called during nib loading when
158+
* objects are being instantiated and connections are being configured. The
159+
* source object represents the origin of the connection, which might be a
160+
* controller object for outlet connections or a user interface control for
161+
* action connections. Setting the source establishes one half of the connection
162+
* relationship that will be completed when the connection is established.
163+
* The source must be compatible with the connection type and capable of
164+
* participating in the intended relationship with the destination object.
165+
*/
51166
- (void) setSource: (id)anObject;
52167
@end
53168

‎Headers/AppKit/NSNibOutletConnector.h‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,38 @@
3131
#import <AppKit/NSNibConnector.h>
3232

3333
APPKIT_EXPORT_CLASS
34+
/**
35+
* NSNibOutletConnector is a specialized connector class that manages outlet
36+
* connections between objects in Interface Builder nib files. This class
37+
* inherits from NSNibConnector and provides the specific implementation for
38+
* establishing outlet connections during nib loading and object instantiation.
39+
* Outlet connections link instance variables or properties of objects to
40+
* other objects in the interface, enabling automatic wiring of user interface
41+
* components to controller objects. The connector maintains references to
42+
* the source object, destination object, and the outlet name that defines
43+
* the connection relationship. During nib loading, NSNibOutletConnector
44+
* instances are processed to establish the actual runtime connections between
45+
* objects, using key-value coding or direct instance variable assignment to
46+
* complete the outlet binding process. This enables the declarative interface
47+
* design paradigm where connections are defined visually and established
48+
* automatically at runtime.
49+
*/
3450
@interface NSNibOutletConnector : NSNibConnector
51+
/**
52+
* Establishes the outlet connection between the source and destination objects
53+
* as specified by this connector. This method performs the actual runtime
54+
* connection process by setting the outlet property or instance variable of
55+
* the source object to reference the destination object. The connection is
56+
* typically established during nib loading after all objects have been
57+
* instantiated and are ready for interconnection. The method uses the outlet
58+
* name stored in the connector to identify which property or instance variable
59+
* should be set on the source object. The connection process may use key-value
60+
* coding mechanisms or direct instance variable access depending on the
61+
* implementation and object characteristics. This method completes the
62+
* declarative connection process defined in Interface Builder by creating
63+
* the actual runtime object references that enable proper user interface
64+
* functionality and object communication.
65+
*/
3566
- (void) establishConnection;
3667
@end
3768

0 commit comments

Comments
 (0)