A component that displays a piano keyboard, whose notes can be clicked on. More...
Inherits Component, MidiKeyboardStateListener, ChangeBroadcaster, Timer, and AsyncUpdater.
Public Types | |
| enum | Orientation { horizontalKeyboard, verticalKeyboardFacingLeft, verticalKeyboardFacingRight } |
The direction of the keyboard. More... | |
| enum | ColourIds { whiteNoteColourId = 0x1005000, blackNoteColourId = 0x1005001, keySeparatorLineColourId = 0x1005002, mouseOverKeyOverlayColourId = 0x1005003, keyDownOverlayColourId = 0x1005004, textLabelColourId = 0x1005005, upDownButtonBackgroundColourId = 0x1005006, upDownButtonArrowColourId = 0x1005007 } |
A set of colour IDs to use to change the colour of various aspects of the keyboard. More... | |
Public Member Functions | |
| MidiKeyboardComponent (MidiKeyboardState &state, Orientation orientation) | |
| Creates a MidiKeyboardComponent. | |
| ~MidiKeyboardComponent () | |
| Destructor. | |
| void | setVelocity (float velocity, bool useMousePositionForVelocity) |
| Changes the velocity used in midi note-on messages that are triggered by clicking on the component. | |
| void | setMidiChannel (int midiChannelNumber) |
| Changes the midi channel number that will be used for events triggered by clicking on the component. | |
| int | getMidiChannel () const noexcept |
| Returns the midi channel that the keyboard is using for midi messages. | |
| void | setMidiChannelsToDisplay (int midiChannelMask) |
| Sets a mask to indicate which incoming midi channels should be represented by key movements. | |
| int | getMidiChannelsToDisplay () const noexcept |
| Returns the current set of midi channels represented by the component. | |
| void | setKeyWidth (float widthInPixels) |
| Changes the width used to draw the white keys. | |
| float | getKeyWidth () const noexcept |
| Returns the width that was set by setKeyWidth(). | |
| void | setOrientation (Orientation newOrientation) |
| Changes the keyboard's current direction. | |
| const Orientation | getOrientation () const noexcept |
| Returns the keyboard's current direction. | |
| void | setAvailableRange (int lowestNote, int highestNote) |
| Sets the range of midi notes that the keyboard will be limited to. | |
| int | getRangeStart () const noexcept |
| Returns the first note in the available range. | |
| int | getRangeEnd () const noexcept |
| Returns the last note in the available range. | |
| void | setLowestVisibleKey (int noteNumber) |
| If the keyboard extends beyond the size of the component, this will scroll it to show the given key at the start. | |
| int | getLowestVisibleKey () const noexcept |
| Returns the number of the first key shown in the component. | |
| int | getBlackNoteLength () const noexcept |
| Returns the length of the black notes. | |
| void | setScrollButtonsVisible (bool canScroll) |
| If set to true, then scroll buttons will appear at either end of the keyboard if there are too many notes to fit them all in the component at once. | |
| int | getKeyStartPosition (const int midiNoteNumber) const |
| Returns the position within the component of the left-hand edge of a key. | |
| void | clearKeyMappings () |
| Deletes all key-mappings. | |
| void | setKeyPressForNote (const KeyPress &key, int midiNoteOffsetFromC) |
| Maps a key-press to a given note. | |
| void | removeKeyPressForNote (int midiNoteOffsetFromC) |
| Removes any key-mappings for a given note. | |
| void | setKeyPressBaseOctave (int newOctaveNumber) |
| Changes the base note above which key-press-triggered notes are played. | |
| void | setOctaveForMiddleC (int octaveNumForMiddleC) |
| This sets the octave number which is shown as the octave number for middle C. | |
| int | getOctaveForMiddleC () const noexcept |
| This returns the value set by setOctaveForMiddleC(). | |
| void | paint (Graphics &g) |
| Components can override this method to draw their content. | |
| void | resized () |
| Called when this component's size has been changed. | |
| void | mouseMove (const MouseEvent &e) |
| Called when the mouse moves inside this component. | |
| void | mouseDrag (const MouseEvent &e) |
| Called when the mouse is moved while a button is held down. | |
| void | mouseDown (const MouseEvent &e) |
| Called when a mouse button is pressed while it's over this component. | |
| void | mouseUp (const MouseEvent &e) |
| Called when a mouse button is released. | |
| void | mouseEnter (const MouseEvent &e) |
| Called when the mouse first enters this component. | |
| void | mouseExit (const MouseEvent &e) |
| Called when the mouse moves out of this component. | |
| void | mouseWheelMove (const MouseEvent &e, float wheelIncrementX, float wheelIncrementY) |
| Called when the mouse-wheel is moved. | |
| void | timerCallback () |
| The user-defined callback routine that actually gets called periodically. | |
| bool | keyStateChanged (bool isKeyDown) |
| Called when a key is pressed or released. | |
| void | focusLost (FocusChangeType cause) |
| Called to indicate that this component has just lost the keyboard focus. | |
| void | handleNoteOn (MidiKeyboardState *source, int midiChannel, int midiNoteNumber, float velocity) |
| Called when one of the MidiKeyboardState's keys is pressed. | |
| void | handleNoteOff (MidiKeyboardState *source, int midiChannel, int midiNoteNumber) |
| Called when one of the MidiKeyboardState's keys is released. | |
| void | handleAsyncUpdate () |
| Called back to do whatever your class needs to do. | |
| void | colourChanged () |
| This method is called when a colour is changed by the setColour() method. | |
Protected Member Functions | |
| virtual void | drawWhiteNote (int midiNoteNumber, Graphics &g, int x, int y, int w, int h, bool isDown, bool isOver, const Colour &lineColour, const Colour &textColour) |
| Draws a white note in the given rectangle. | |
| virtual void | drawBlackNote (int midiNoteNumber, Graphics &g, int x, int y, int w, int h, bool isDown, bool isOver, const Colour ¬eFillColour) |
| Draws a black note in the given rectangle. | |
| virtual const String | getWhiteNoteText (const int midiNoteNumber) |
| Allows text to be drawn on the white notes. | |
| virtual void | drawUpDownButton (Graphics &g, int w, int h, const bool isMouseOver, const bool isButtonPressed, const bool movesOctavesUp) |
| Draws the up and down buttons that change the base note. | |
| virtual bool | mouseDownOnKey (int midiNoteNumber, const MouseEvent &e) |
| Callback when the mouse is clicked on a key. | |
| virtual void | mouseDraggedToKey (int midiNoteNumber, const MouseEvent &e) |
| Callback when the mouse is dragged from one key onto another. | |
| virtual void | getKeyPosition (int midiNoteNumber, float keyWidth, int &x, int &w) const |
| Calculates the positon of a given midi-note. | |
A component that displays a piano keyboard, whose notes can be clicked on.
This component will mimic a physical midi keyboard, showing the current state of a MidiKeyboardState object. When the on-screen keys are clicked on, it will play these notes by calling the noteOn() and noteOff() methods of its MidiKeyboardState object.
Another feature is that the computer keyboard can also be used to play notes. By default it maps the top two rows of a standard querty keyboard to the notes, but these can be remapped if needed. It will only respond to keypresses when it has the keyboard focus, so to disable this feature you can call setWantsKeyboardFocus (false).
The component is also a ChangeBroadcaster, so if you want to be informed when the keyboard is scrolled, you can register a ChangeListener for callbacks.
The direction of the keyboard.
A set of colour IDs to use to change the colour of various aspects of the keyboard.
These constants can be used either via the Component::setColour(), or LookAndFeel::setColour() methods.
| MidiKeyboardComponent::MidiKeyboardComponent | ( | MidiKeyboardState & | state, |
| Orientation | orientation | ||
| ) |
Creates a MidiKeyboardComponent.
| state | the midi keyboard model that this component will represent |
| orientation | whether the keyboard is horizonal or vertical |
| MidiKeyboardComponent::~MidiKeyboardComponent | ( | ) |
Destructor.
| void MidiKeyboardComponent::setVelocity | ( | float | velocity, |
| bool | useMousePositionForVelocity | ||
| ) |
Changes the velocity used in midi note-on messages that are triggered by clicking on the component.
Values are 0 to 1.0, where 1.0 is the heaviest.
| void MidiKeyboardComponent::setMidiChannel | ( | int | midiChannelNumber ) |
Changes the midi channel number that will be used for events triggered by clicking on the component.
The channel must be between 1 and 16 (inclusive). This is the channel that will be passed on to the MidiKeyboardState::noteOn() method when the user clicks the component.
Although this is the channel used for outgoing events, the component can display incoming events from more than one channel - see setMidiChannelsToDisplay()
| int MidiKeyboardComponent::getMidiChannel | ( | ) | const |
Returns the midi channel that the keyboard is using for midi messages.
| void MidiKeyboardComponent::setMidiChannelsToDisplay | ( | int | midiChannelMask ) |
Sets a mask to indicate which incoming midi channels should be represented by key movements.
The mask is a set of bits, where bit 0 = midi channel 1, bit 1 = midi channel 2, etc.
If the MidiKeyboardState has a key down for any of the channels whose bits are set in this mask, the on-screen keys will also go down.
By default, this mask is set to 0xffff (all channels displayed).
| int MidiKeyboardComponent::getMidiChannelsToDisplay | ( | ) | const |
Returns the current set of midi channels represented by the component.
This is the value that was set with setMidiChannelsToDisplay().
| void MidiKeyboardComponent::setKeyWidth | ( | float | widthInPixels ) |
Changes the width used to draw the white keys.
| float MidiKeyboardComponent::getKeyWidth | ( | ) | const |
Returns the width that was set by setKeyWidth().
| void MidiKeyboardComponent::setOrientation | ( | Orientation | newOrientation ) |
Changes the keyboard's current direction.
| const Orientation MidiKeyboardComponent::getOrientation | ( | ) | const |
Returns the keyboard's current direction.
| void MidiKeyboardComponent::setAvailableRange | ( | int | lowestNote, |
| int | highestNote | ||
| ) |
Sets the range of midi notes that the keyboard will be limited to.
By default the range is 0 to 127 (inclusive), but you can limit this if you only want a restricted set of the keys to be shown.
Note that the values here are inclusive and must be between 0 and 127.
| int MidiKeyboardComponent::getRangeStart | ( | ) | const |
Returns the first note in the available range.
| int MidiKeyboardComponent::getRangeEnd | ( | ) | const |
Returns the last note in the available range.
| void MidiKeyboardComponent::setLowestVisibleKey | ( | int | noteNumber ) |
If the keyboard extends beyond the size of the component, this will scroll it to show the given key at the start.
Whenever the keyboard's position is changed, this will use the ChangeBroadcaster base class to send a callback to any ChangeListeners that have been registered.
| int MidiKeyboardComponent::getLowestVisibleKey | ( | ) | const |
Returns the number of the first key shown in the component.
| int MidiKeyboardComponent::getBlackNoteLength | ( | ) | const |
Returns the length of the black notes.
This will be their vertical or horizontal length, depending on the keyboard's orientation.
| void MidiKeyboardComponent::setScrollButtonsVisible | ( | bool | canScroll ) |
If set to true, then scroll buttons will appear at either end of the keyboard if there are too many notes to fit them all in the component at once.
| int MidiKeyboardComponent::getKeyStartPosition | ( | const int | midiNoteNumber ) | const |
Returns the position within the component of the left-hand edge of a key.
Depending on the keyboard's orientation, this may be a horizontal or vertical distance, in either direction.
| void MidiKeyboardComponent::clearKeyMappings | ( | ) |
Deletes all key-mappings.
| void MidiKeyboardComponent::setKeyPressForNote | ( | const KeyPress & | key, |
| int | midiNoteOffsetFromC | ||
| ) |
Maps a key-press to a given note.
| key | the key that should trigger the note |
| midiNoteOffsetFromC | how many semitones above C the triggered note should be. The actual midi note that gets played will be this value + (12 * the current base octave). To change the base octave, see setKeyPressBaseOctave() |
| void MidiKeyboardComponent::removeKeyPressForNote | ( | int | midiNoteOffsetFromC ) |
Removes any key-mappings for a given note.
For a description of what the note number means, see setKeyPressForNote().
| void MidiKeyboardComponent::setKeyPressBaseOctave | ( | int | newOctaveNumber ) |
Changes the base note above which key-press-triggered notes are played.
The set of key-mappings that trigger notes can be moved up and down to cover the entire scale using this method.
The value passed in is an octave number between 0 and 10 (inclusive), and indicates which C is the base note to which the key-mapped notes are relative.
| void MidiKeyboardComponent::setOctaveForMiddleC | ( | int | octaveNumForMiddleC ) |
This sets the octave number which is shown as the octave number for middle C.
This affects only the default implementation of getWhiteNoteText(), which passes this octave number to MidiMessage::getMidiNoteName() in order to get the note text. See MidiMessage::getMidiNoteName() for more info about the parameter.
By default this value is set to 3.
| int MidiKeyboardComponent::getOctaveForMiddleC | ( | ) | const |
This returns the value set by setOctaveForMiddleC().
| void MidiKeyboardComponent::paint | ( | Graphics & | g ) | [virtual] |
Components can override this method to draw their content.
The paint() method gets called when a region of a component needs redrawing, either because the component's repaint() method has been called, or because something has happened on the screen that means a section of a window needs to be redrawn.
Any child components will draw themselves over whatever this method draws. If you need to paint over the top of your child components, you can also implement the paintOverChildren() method to do this.
If you want to cause a component to redraw itself, this is done asynchronously - calling the repaint() method marks a region of the component as "dirty", and the paint() method will automatically be called sometime later, by the message thread, to paint any bits that need refreshing. In Juce (and almost all modern UI frameworks), you never redraw something synchronously.
You should never need to call this method directly - to take a snapshot of the component you could use createComponentSnapshot() or paintEntireComponent().
| g | the graphics context that must be used to do the drawing operations. |
Reimplemented from Component.
| void MidiKeyboardComponent::resized | ( | ) | [virtual] |
Called when this component's size has been changed.
A component can implement this method to do things such as laying out its child components when its width or height changes.
The method is called synchronously as a result of the setBounds or setSize methods, so repeatedly changing a components size will repeatedly call its resized method (unlike things like repainting, where multiple calls to repaint are coalesced together).
If the component is a top-level window on the desktop, its size could also be changed by operating-system factors beyond the application's control.
Reimplemented from Component.
| void MidiKeyboardComponent::mouseMove | ( | const MouseEvent & | e ) | [virtual] |
Called when the mouse moves inside this component.
If the mouse button isn't pressed and the mouse moves over a component, this will be called to let the component react to this.
A component will always get a mouseEnter callback before a mouseMove.
| e | details about the position and status of the mouse event |
Reimplemented from Component.
| void MidiKeyboardComponent::mouseDrag | ( | const MouseEvent & | e ) | [virtual] |
Called when the mouse is moved while a button is held down.
When a mouse button is pressed inside a component, that component receives mouseDrag callbacks each time the mouse moves, even if the mouse strays outside the component's bounds.
If you want to be able to drag things off the edge of a component and have the component scroll when you get to the edges, the beginDragAutoRepeat() method might be useful.
| e | details about the position and status of the mouse event |
Reimplemented from Component.
| void MidiKeyboardComponent::mouseDown | ( | const MouseEvent & | e ) | [virtual] |
Called when a mouse button is pressed while it's over this component.
The MouseEvent object passed in contains lots of methods for finding out which button was pressed, as well as which modifier keys (e.g. shift, ctrl) were held down at the time.
Once a button is held down, the mouseDrag method will be called when the mouse moves, until the button is released.
| e | details about the position and status of the mouse event |
Reimplemented from Component.
| void MidiKeyboardComponent::mouseUp | ( | const MouseEvent & | e ) | [virtual] |
Called when a mouse button is released.
A mouseUp callback is sent to the component in which a button was pressed even if the mouse is actually over a different component when the button is released.
The MouseEvent object passed in contains lots of methods for finding out which buttons were down just before they were released.
| e | details about the position and status of the mouse event |
Reimplemented from Component.
| void MidiKeyboardComponent::mouseEnter | ( | const MouseEvent & | e ) | [virtual] |
Called when the mouse first enters this component.
If the mouse button isn't pressed and the mouse moves into a component, this will be called to let the component react to this.
When the mouse button is pressed and held down while being moved in or out of a component, no mouseEnter or mouseExit callbacks are made - only mouseDrag messages are sent to the component that the mouse was originally clicked on, until the button is released.
If you're writing a component that needs to repaint itself when the mouse enters and exits, it might be quicker to use the setRepaintsOnMouseActivity() method.
| e | details about the position and status of the mouse event |
Reimplemented from Component.
| void MidiKeyboardComponent::mouseExit | ( | const MouseEvent & | e ) | [virtual] |
Called when the mouse moves out of this component.
This will be called when the mouse moves off the edge of this component.
If the mouse button was pressed, and it was then dragged off the edge of the component and released, then this callback will happen when the button is released, after the mouseUp callback.
If you're writing a component that needs to repaint itself when the mouse enters and exits, it might be quicker to use the setRepaintsOnMouseActivity() method.
| e | details about the position and status of the mouse event |
Reimplemented from Component.
| void MidiKeyboardComponent::mouseWheelMove | ( | const MouseEvent & | e, |
| float | wheelIncrementX, | ||
| float | wheelIncrementY | ||
| ) | [virtual] |
Called when the mouse-wheel is moved.
This callback is sent to the component that the mouse is over when the wheel is moved.
If not overridden, the component will forward this message to its parent, so that parent components can collect mouse-wheel messages that happen to child components which aren't interested in them.
| e | details about the position and status of the mouse event |
| wheelIncrementX | the speed and direction of the horizontal scroll-wheel - a positive value means the wheel has been pushed to the right, negative means it was pushed to the left |
| wheelIncrementY | the speed and direction of the vertical scroll-wheel - a positive value means the wheel has been pushed upwards, negative means it was pushed downwards |
Reimplemented from Component.
| void MidiKeyboardComponent::timerCallback | ( | ) | [virtual] |
The user-defined callback routine that actually gets called periodically.
It's perfectly ok to call startTimer() or stopTimer() from within this callback to change the subsequent intervals.
Implements Timer.
| bool MidiKeyboardComponent::keyStateChanged | ( | bool | isKeyDown ) | [virtual] |
Called when a key is pressed or released.
Whenever a key on the keyboard is pressed or released (including modifier keys like shift and ctrl), this method will be called on the component that currently has the keyboard focus. Remember that a component will only be given the focus if its setWantsKeyboardFocus() method has been used to enable this.
If your implementation returns true, the event will be consumed and not passed on to any other listeners. If it returns false, then any KeyListeners that have been registered with this component will have their keyStateChanged methods called. As soon as one of these returns true, the process will stop, but if they all return false, the event will be passed upwards to this component's parent, and so on.
The default implementation of this method does nothing and returns false.
To find out which keys are up or down at any time, see the KeyPress::isKeyCurrentlyDown() method.
| isKeyDown | true if a key has been pressed; false if it has been released |
Reimplemented from Component.
| void MidiKeyboardComponent::focusLost | ( | FocusChangeType | cause ) | [virtual] |
Called to indicate that this component has just lost the keyboard focus.
Reimplemented from Component.
| void MidiKeyboardComponent::handleNoteOn | ( | MidiKeyboardState * | source, |
| int | midiChannel, | ||
| int | midiNoteNumber, | ||
| float | velocity | ||
| ) | [virtual] |
Called when one of the MidiKeyboardState's keys is pressed.
This will be called synchronously when the state is either processing a buffer in its MidiKeyboardState::processNextMidiBuffer() method, or when a note is being played with its MidiKeyboardState::noteOn() method.
Note that this callback could happen from an audio callback thread, so be careful not to block, and avoid any UI activity in the callback.
Implements MidiKeyboardStateListener.
| void MidiKeyboardComponent::handleNoteOff | ( | MidiKeyboardState * | source, |
| int | midiChannel, | ||
| int | midiNoteNumber | ||
| ) | [virtual] |
Called when one of the MidiKeyboardState's keys is released.
This will be called synchronously when the state is either processing a buffer in its MidiKeyboardState::processNextMidiBuffer() method, or when a note is being played with its MidiKeyboardState::noteOff() method.
Note that this callback could happen from an audio callback thread, so be careful not to block, and avoid any UI activity in the callback.
Implements MidiKeyboardStateListener.
| void MidiKeyboardComponent::handleAsyncUpdate | ( | ) | [virtual] |
Called back to do whatever your class needs to do.
This method is called by the message thread at the next convenient time after the triggerAsyncUpdate() method has been called.
Implements AsyncUpdater.
| void MidiKeyboardComponent::colourChanged | ( | ) | [virtual] |
This method is called when a colour is changed by the setColour() method.
Reimplemented from Component.
| virtual void MidiKeyboardComponent::drawWhiteNote | ( | int | midiNoteNumber, |
| Graphics & | g, | ||
| int | x, | ||
| int | y, | ||
| int | w, | ||
| int | h, | ||
| bool | isDown, | ||
| bool | isOver, | ||
| const Colour & | lineColour, | ||
| const Colour & | textColour | ||
| ) | [protected, virtual] |
Draws a white note in the given rectangle.
isOver indicates whether the mouse is over the key, isDown indicates whether the key is currently pressed down.
When doing this, be sure to note the keyboard's orientation.
| virtual void MidiKeyboardComponent::drawBlackNote | ( | int | midiNoteNumber, |
| Graphics & | g, | ||
| int | x, | ||
| int | y, | ||
| int | w, | ||
| int | h, | ||
| bool | isDown, | ||
| bool | isOver, | ||
| const Colour & | noteFillColour | ||
| ) | [protected, virtual] |
Draws a black note in the given rectangle.
isOver indicates whether the mouse is over the key, isDown indicates whether the key is currently pressed down.
When doing this, be sure to note the keyboard's orientation.
| virtual const String MidiKeyboardComponent::getWhiteNoteText | ( | const int | midiNoteNumber ) | [protected, virtual] |
Allows text to be drawn on the white notes.
By default this is used to label the C in each octave, but could be used for other things.
| virtual void MidiKeyboardComponent::drawUpDownButton | ( | Graphics & | g, |
| int | w, | ||
| int | h, | ||
| const bool | isMouseOver, | ||
| const bool | isButtonPressed, | ||
| const bool | movesOctavesUp | ||
| ) | [protected, virtual] |
Draws the up and down buttons that change the base note.
| virtual bool MidiKeyboardComponent::mouseDownOnKey | ( | int | midiNoteNumber, |
| const MouseEvent & | e | ||
| ) | [protected, virtual] |
Callback when the mouse is clicked on a key.
You could use this to do things like handle right-clicks on keys, etc.
Return true if you want the click to trigger the note, or false if you want to handle it yourself and not have the note played.
| virtual void MidiKeyboardComponent::mouseDraggedToKey | ( | int | midiNoteNumber, |
| const MouseEvent & | e | ||
| ) | [protected, virtual] |
Callback when the mouse is dragged from one key onto another.
| virtual void MidiKeyboardComponent::getKeyPosition | ( | int | midiNoteNumber, |
| float | keyWidth, | ||
| int & | x, | ||
| int & | w | ||
| ) | const [protected, virtual] |
Calculates the positon of a given midi-note.
This can be overridden to create layouts with custom key-widths.
| midiNoteNumber | the note to find |
| keyWidth | the desired width in pixels of one key - see setKeyWidth() |
| x | the x position of the left-hand edge of the key (this method always works in terms of a horizontal keyboard) |
| w | the width of the key |
