-
Notifications
You must be signed in to change notification settings - Fork 5
/
WhereToFindWhatIWant.pier
86 lines (64 loc) · 3.54 KB
/
WhereToFindWhatIWant.pier
1
2
3
4
5
6
7
8
9
10
11
12
13
14
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
!! Where to find what I want
@sec_where_to_find_what_I_want
All the ''Spec'' models for basic widgets have an API that is explicitly documented through the use of pragmas.
This section explains where to find the API of a model and meaning of the meta information that is attached to the API methods.
Each model contains at least two protocols that group the public API methods.
The first protocol is named ""protocol"".
It gathers all the methods that set or get the different state elements of the model plus the behavioral methods acting directly on these elements.
The second protocol is named ""protocol-events"".
It gathers all the methods that are used to register to a state change.
All the meta-information of public API methods is documented through the use of pragmas that start with ''api:''.
There are three types of public API methods: getters, setters and registration methods.
!!! Meta information for getters
The pragma for getters is always ==<api: #inspect>==.
For example, the code in *ex_api_getter* shows how the ''action'' method in ""ButtonModel"" is implemented.
[[[label=ex_api_getter|caption=Implementation of ButtonModel>>#action|language=Smalltalk
action
<api: #inspect>
"get the block performed when the button is clicked"
^ actionHolder value
]]]
!!! Meta information for setters
The pragma for setters is a bit more complex.
The pattern of the pragma is ==<api: typeOfState getter: getterSelector registration: registrationMethodSelector>==.
In this pattern, ''typeOfState'' , ''getterSelector'' and ''registrationMethodSelector'' need to be substituted by the relevant values for this setter.
The ''getterSelector'' specifies the name of the getter method (a Symbol) that returns the state set by this method.
The ''registrationMethodSelector'' states the name of the method (a Symbol) that needs to be used to register to changes in the state.
''typeOfState'' gives the type of the state being set by this setter.
The possible types are as follows:
- #block indicates a block,
- #boolean indicates a boolean,
- #color indicates a Color,
- #image indicates a Form,
- #integer indicates an integer,
- #point indicates a Point,
- #string indicates a String,
- #st indicates any other type of ''Smalltalk'' object.
For example, the code in *ex_api_setter* shows how ''actions:'' is implemented in ""ButtonModel"".
[[[label=ex_api_setter|caption=Implementation of ButtonModel>>#action:|language=Smalltalk
action: aBlock
<api: #block getter: #getAction registration: #whenActionChangedDo:>
"set the block performed when the button is clicked"
actionHolder value: aBlock
]]]
!!! Meta information for registration methods
The pragma for registration methods information is always ''<api: #event>''.
For example, the code in *ex_api_registration* shows how the method ''whenActionChangedDo:'' is implemented in ""ButtonModel"".
[[[label=ex_api_registration|caption=Implementation of ButtonModel>>#whenActionChangedDo|language=Smalltalk
whenActionChangedDo: aBlock
<api: #event>
"Set the block performed when the action to perform is changed"
actionHolder whenChangedDo: aBlock
]]]
!!! Meta information for behavioral methods
The other methods should be mainly methods that implement some
behavior of the widget.
The pragma for these methods is ''<api: #do>''.
For example, *ex_resetSelection* shows how ''resetSelection'' is implemented in ""ListModel"".
[[[label=ex_resetSelection|caption=Implementation of ListModel>>#resetSelection|language=Smalltalk
resetSelection
<api: #do>
"Unselect every items"
selectionHolder reset.
multiSelectionHolder removeAll
]]]