Source code: com/virtuosotechnologies/asaph/model/SongBlock.java
1 /*
2 ================================================================================
3
4 FILE: SongBlock.java
5
6 PROJECT:
7
8 Asaph
9
10 CONTENTS:
11
12 SongBlock 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
47 /**
48 * This interface represents a block of lines in a song. A Song consists of
49 * an ordered list of blocks, and each block consists of an ordered list of
50 * lines. Blocks also have an indent level.
51 */
52 public interface SongBlock
53 extends SongMember
54 {
55 //-------------------------------------------------------------------------
56 // Accessor methods
57 //-------------------------------------------------------------------------
58
59 /**
60 * Get the indent level
61 *
62 * @return indent level
63 */
64 public int getIndentLevel();
65
66
67 /**
68 * Get the number of lines
69 *
70 * @return number of lines
71 */
72 public int getLineCount();
73
74
75 /**
76 * Get the nth line
77 *
78 * @param n index
79 * @return line
80 */
81 public SongLine getNthLine(
82 int n);
83
84
85 /**
86 * Get the next line following reference.
87 * If reference is null, returns the first line.
88 * If reference is the last line, returns null;
89 *
90 * @param reference reference SongLine
91 * @return next line
92 * @exception IllegalArgumentException reference is not a member
93 */
94 public SongLine getNextLine(
95 SongLine reference);
96
97
98 /**
99 * Get the previous line preceding reference.
100 * If reference is null, returns the last line.
101 * If reference is the first line, returns null;
102 *
103 * @param reference reference SongLine
104 * @return previous line
105 * @exception IllegalArgumentException reference is not a member
106 */
107 public SongLine getPreviousLine(
108 SongLine reference);
109
110
111 /**
112 * Get a string ID that can be used to serialize references to this
113 * SongBlock. The ID is guaranteed to be unique among SongBlocks within
114 * the owning Song, and will remain the same for the same SongBlock across
115 * different executions of the tool. However, two SongBlocks from different
116 * Songs may have the same string ID, and the same string ID may be
117 * shared between SongBlocks, Variations and ChordSets within the same
118 * Song.
119 *
120 * @return a unique serializable String ID for this SongBlock
121 */
122 public String getSerializableID();
123
124
125 //-------------------------------------------------------------------------
126 // Mutation methods
127 //-------------------------------------------------------------------------
128
129 /**
130 * Set the indent level
131 *
132 * @param indent new indent level
133 * @param undoListener listener to notify if an undoable edit is generated,
134 * or null to suppress generation of undoable edits
135 */
136 public void setIndentLevel(
137 int indent,
138 UndoableEditListener undoListener);
139
140
141 /**
142 * Add a line at the given position.
143 *
144 * @param before insert before this line, or at the end if null
145 * @param undoListener listener to notify if an undoable edit is generated,
146 * or null to suppress generation of undoable edits
147 * @return added SongLine
148 * @exception IllegalArgumentException before is not a member
149 */
150 public SongLine insertLineBefore(
151 SongLine before,
152 UndoableEditListener undoListener);
153
154
155 /**
156 * Add a line at the given position.
157 *
158 * @param after insert after this line, or at the beginning if null
159 * @param undoListener listener to notify if an undoable edit is generated,
160 * or null to suppress generation of undoable edits
161 * @return added SongLine
162 * @exception IllegalArgumentException after is not a member
163 */
164 public SongLine insertLineAfter(
165 SongLine after,
166 UndoableEditListener undoListener);
167
168
169 /**
170 * Remove the given line.
171 *
172 * @param line line to remove
173 * @param undoListener listener to notify if an undoable edit is generated,
174 * or null to suppress generation of undoable edits
175 * @exception IllegalArgumentException line is not present
176 * @exception NullPointerException line was null
177 */
178 public void removeLine(
179 SongLine line,
180 UndoableEditListener undoListener);
181 }