Source code: com/virtuosotechnologies/asaph/model/SongLine.java
1 /*
2 ================================================================================
3
4 FILE: SongLine.java
5
6 PROJECT:
7
8 Asaph
9
10 CONTENTS:
11
12 SongLine interface in an Asaph model
13
14 PROGRAMMERS:
15
16 Daniel Azuma (DA) <dazuma@kagi.com>
17
18 COPYRIGHT:
19
20 Copyright (C) 2003 Daniel Azuma (dazuma@kagi.com)
21
22 This program is free software; you can redistribute it and/or
23 modify it under the terms of the GNU General Public License as
24 published by the Free Software Foundation; either version 2
25 of the License, or (at your option) any later version.
26
27 This program is distributed in the hope that it will be useful,
28 but WITHOUT ANY WARRANTY; without even the implied warranty of
29 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
30 GNU General Public License for more details.
31
32 You should have received a copy of the GNU General Public
33 License along with this program; if not, write to
34 Free Software Foundation, Inc.
35 59 Temple Place, Suite 330
36 Boston, MA 02111-1307 USA
37
38 ================================================================================
39 */
40
41
42 package com.virtuosotechnologies.asaph.model;
43
44 import javax.swing.event.UndoableEditListener;
45
46 import com.virtuosotechnologies.asaph.model.notation.Chord;
47
48
49 /**
50 * This interface represents a line in a song. A line is made up of a
51 * sequence of SongLineMembers, which are strings, comments or chord
52 * annotations. Lines are contained within SongBlocks.
53 */
54 public interface SongLine
55 extends SongMember
56 {
57 //-------------------------------------------------------------------------
58 // Accessor methods
59 //-------------------------------------------------------------------------
60
61 /**
62 * Get the containing song block
63 *
64 * @return SongBlock containing this line
65 */
66 public SongBlock getSongBlock();
67
68
69 /**
70 * Get the indent level
71 *
72 * @return indent level
73 */
74 public int getIndentLevel();
75
76
77 /**
78 * Get the number of members
79 *
80 * @return number of members
81 */
82 public int getMemberCount();
83
84
85 /**
86 * Get the nth member
87 *
88 * @param n index
89 * @return member
90 */
91 public SongLineMember getNthMember(
92 int n);
93
94
95 /**
96 * Get the next member following reference.
97 * If reference is null, returns the first member.
98 * If reference is the last member, returns null;
99 *
100 * @param reference reference SongLineMember
101 * @return next member
102 * @exception IllegalArgumentException reference is not a member
103 */
104 public SongLineMember getNextMember(
105 SongLineMember reference);
106
107
108 /**
109 * Get the previous member preceding reference.
110 * If reference is null, returns the last member.
111 * If reference is the first member, returns null;
112 *
113 * @param reference reference SongLineMember
114 * @return previous member
115 * @exception IllegalArgumentException reference is not a member
116 */
117 public SongLineMember getPreviousMember(
118 SongLineMember reference);
119
120
121 /**
122 * Get the number of members in the given chord set
123 *
124 * @param set ChordSet to filter by, or null for no chords
125 * @return number of members
126 */
127 public int getMemberCount(
128 ChordSet set);
129
130
131 /**
132 * Get the nth member
133 *
134 * @param n index
135 * @param set ChordSet to filter by, or null for no chords
136 * @return member
137 */
138 public SongLineMember getNthMember(
139 int n,
140 ChordSet set);
141
142
143 /**
144 * Get the next member following reference.
145 * If reference is null, returns the first member.
146 * If reference is the last member, returns null;
147 *
148 * @param reference reference SongLineMember
149 * @param set ChordSet to filter by, or null for no chords
150 * @return next member
151 * @exception IllegalArgumentException reference is not a member
152 */
153 public SongLineMember getNextMember(
154 SongLineMember reference,
155 ChordSet set);
156
157
158 /**
159 * Get the previous member preceding reference.
160 * If reference is null, returns the last member.
161 * If reference is the first member, returns null;
162 *
163 * @param reference reference SongLineMember
164 * @param set ChordSet to filter by, or null for no chords
165 * @return previous member
166 * @exception IllegalArgumentException reference is not a member
167 */
168 public SongLineMember getPreviousMember(
169 SongLineMember reference,
170 ChordSet set);
171
172
173 //-------------------------------------------------------------------------
174 // Mutation methods
175 //-------------------------------------------------------------------------
176
177 /**
178 * Set the indent level
179 *
180 * @param indent new indent level
181 * @param undoListener listener to notify if an undoable edit is generated,
182 * or null to suppress generation of undoable edits
183 */
184 public void setIndentLevel(
185 int indent,
186 UndoableEditListener undoListener);
187
188
189 /**
190 * Add a text string at the given position.
191 *
192 * @param before insert before this member, or at the end if null
193 * @param str string value
194 * @param undoListener listener to notify if an undoable edit is generated,
195 * or null to suppress generation of undoable edits
196 * @return added TextString
197 * @exception IllegalArgumentException before is not a member
198 * @exception NullPointerException str was null
199 */
200 public TextString insertTextStringBefore(
201 SongLineMember before,
202 String str,
203 UndoableEditListener undoListener);
204
205
206 /**
207 * Add a text string at the given position.
208 *
209 * @param after insert after this member, or at the beginning if null
210 * @param str string value
211 * @param undoListener listener to notify if an undoable edit is generated,
212 * or null to suppress generation of undoable edits
213 * @return added TextString
214 * @exception IllegalArgumentException after is not a member
215 * @exception NullPointerException str was null
216 */
217 public TextString insertTextStringAfter(
218 SongLineMember after,
219 String str,
220 UndoableEditListener undoListener);
221
222
223 /**
224 * Add a comment string at the given position.
225 *
226 * @param before insert before this member, or at the end if null
227 * @param str string value
228 * @param undoListener listener to notify if an undoable edit is generated,
229 * or null to suppress generation of undoable edits
230 * @return added CommentString
231 * @exception IllegalArgumentException before is not a member
232 * @exception NullPointerException str was null
233 */
234 public CommentString insertCommentStringBefore(
235 SongLineMember before,
236 String str,
237 UndoableEditListener undoListener);
238
239
240 /**
241 * Add a comment string at the given position.
242 *
243 * @param after insert after this member, or at the beginning if null
244 * @param str string value
245 * @param undoListener listener to notify if an undoable edit is generated,
246 * or null to suppress generation of undoable edits
247 * @return added CommentString
248 * @exception IllegalArgumentException after is not a member
249 * @exception NullPointerException str was null
250 */
251 public CommentString insertCommentStringAfter(
252 SongLineMember after,
253 String str,
254 UndoableEditListener undoListener);
255
256
257 /**
258 * Add a chord annotation at the given position.
259 *
260 * @param before insert before this member, or at the end if null
261 * @param cs ChordSet for the annotation. May not be null.
262 * @param primary primary chord for the annotation. May not be null.
263 * @param preceding array of preceding chords. May be null.
264 * @param following array of following chords. May be null.
265 * @param undoListener listener to notify if an undoable edit is generated,
266 * or null to suppress generation of undoable edits
267 * @return added ChordAnnotation
268 * @exception IllegalArgumentException before or cs is not a member
269 * @exception NullPointerException cs was null
270 */
271 public ChordAnnotation insertChordAnnotationBefore(
272 SongLineMember before,
273 ChordSet cs,
274 Chord primary,
275 Chord[] preceding,
276 Chord[] following,
277 UndoableEditListener undoListener);
278
279
280 /**
281 * Add a chord annotation at the given position.
282 *
283 * @param after insert after this member, or at the beginning if null
284 * @param cs ChordSet for the annotation. May not be null.
285 * @param primary primary chord for the annotation. May not be null.
286 * @param preceding array of preceding chords. May be null.
287 * @param following array of following chords. May be null.
288 * @param undoListener listener to notify if an undoable edit is generated,
289 * or null to suppress generation of undoable edits
290 * @return added ChordAnnotation
291 * @exception IllegalArgumentException after or cs is not a member
292 * @exception NullPointerException cs was null
293 */
294 public ChordAnnotation insertChordAnnotationAfter(
295 SongLineMember after,
296 ChordSet cs,
297 Chord primary,
298 Chord[] preceding,
299 Chord[] following,
300 UndoableEditListener undoListener);
301
302
303 /**
304 * Remove the given member.
305 *
306 * @param member member to remove
307 * @param undoListener listener to notify if an undoable edit is generated,
308 * or null to suppress generation of undoable edits
309 * @exception IllegalArgumentException member is not a member
310 * @exception NullPointerException member was null
311 */
312 public void removeMember(
313 SongLineMember member,
314 UndoableEditListener undoListener);
315 }