Source code: com/virtuosotechnologies/asaph/model/ChordSet.java
1 /*
2 ================================================================================
3
4 FILE: ChordSet.java
5
6 PROJECT:
7
8 Asaph
9
10 CONTENTS:
11
12 ChordSet interface
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.Note;
47
48
49 /**
50 * A set of chords for a song. Most songs will only have one ChordSet,
51 * but some may have multiple, especially if there are alternate tunes.
52 */
53 public interface ChordSet
54 extends SongMember
55 {
56 //-------------------------------------------------------------------------
57 // Accessor methods
58 //-------------------------------------------------------------------------
59
60 /**
61 * Get a SimpleString containing the name of the chord set.
62 * Every ChordSet will have a name, even if it is the empty string.
63 *
64 * @return name
65 */
66 public SimpleString getName();
67
68
69 /**
70 * Get a SimpleString containing the key signature type. This string
71 * is typically the string that gets concatenated to the note to form
72 * a key signature. Often it begins with a space. Every ChordSet
73 * will have a key signature type, even if it is the empty string.
74 *
75 * @return key signature type
76 */
77 public SimpleString getKeySignatureType();
78
79
80 /**
81 * Get the ChordSetKey representing the native key signature.
82 *
83 * @return native key signature
84 */
85 public ChordSetKey getNativeKey();
86
87
88 /**
89 * Get the number of alternate keys
90 *
91 * @return number of alternate keys
92 */
93 public int getAlternateKeyCount();
94
95
96 /**
97 * Get the next alternate key following reference.
98 * If reference is null, returns the first alternate key.
99 * If reference is the last alternate key, returns null;
100 *
101 * @param reference reference ChordSetKey
102 * @return next alternate key
103 * @exception IllegalArgumentException reference is not a member
104 */
105 public ChordSetKey getNextAlternateKey(
106 ChordSetKey reference);
107
108
109 /**
110 * Get the previous alternate key preceding reference.
111 * If reference is null, returns the last alternate key.
112 * If reference is the first alternate key, returns null;
113 *
114 * @param reference reference ChordSetKey
115 * @return previous alternate key
116 * @exception IllegalArgumentException reference is not a member
117 */
118 public ChordSetKey getPreviousAlternateKey(
119 ChordSetKey reference);
120
121
122 /**
123 * Get a string ID that can be used to serialize references to this
124 * ChordSet. The ID is guaranteed to be unique among ChordSets within
125 * the owning Song, and will remain the same for the same ChordSet across
126 * different executions of the tool. However, two ChordSets from different
127 * Songs may have the same string ID, and the same string ID may be
128 * shared between SongBlocks, Variations and ChordSets within the same
129 * Song.
130 *
131 * @return a unique serializable String ID for this ChordSet
132 */
133 public String getSerializableID();
134
135
136 //-------------------------------------------------------------------------
137 // Mutation methods
138 //-------------------------------------------------------------------------
139
140 /**
141 * Add a new alternate key to the chord set.
142 *
143 * @param note key note
144 * @param undoListener listener to notify if an undoable edit is generated,
145 * or null to suppress generation of undoable edits
146 * @return added alternate key
147 * @exception NullPointerException note was null
148 */
149 public ChordSetKey addAlternateKey(
150 Note note,
151 UndoableEditListener undoListener);
152
153
154 /**
155 * Remove the given alternate key from the chord set.
156 *
157 * @param alternateKey ChordSetKey to remove
158 * @param undoListener listener to notify if an undoable edit is generated,
159 * or null to suppress generation of undoable edits
160 * @exception IllegalArgumentException alternateKey is not present
161 * @exception NullPointerException alternateKey was null
162 */
163 public void removeAlternateKey(
164 ChordSetKey alternateKey,
165 UndoableEditListener undoListener);
166 }