Audacity  2.2.0
LabelTrack Class Referencefinal

A LabelTrack is a Track that holds labels (LabelStruct). More...

#include <LabelTrack.h>

Inheritance diagram for LabelTrack:
Track CommonTrackPanelCell XMLTagHandler TrackPanelCell


struct  Flags

Public Types

using Holder = std::unique_ptr< LabelTrack >
- Public Types inherited from Track
enum  { LeftChannel = 0, RightChannel = 1, MonoChannel = 2 }
enum  TrackKindEnum {
  None, Wave, Label, Time,
enum  : unsigned { DefaultHeight = 150 }
using Holder = std::unique_ptr< Track >

Public Member Functions

bool IsGoodLabelFirstKey (const wxKeyEvent &evt)
 Returns true for keys we capture to start a label. More...
bool IsGoodLabelEditKey (const wxKeyEvent &evt)
 This returns true for keys we capture for label editing. More...
bool IsTextSelected ()
void CreateCustomGlyphs ()
 LabelTrack (const std::shared_ptr< DirManager > &projDirManager)
 LabelTrack (const LabelTrack &orig)
virtual ~LabelTrack ()
std::vector< UIHandlePtrDetailedHitTest (const TrackPanelMouseState &state, const AudacityProject *pProject, int currentTool, bool bMultiTool) override
bool DoCaptureKey (wxKeyEvent &event)
unsigned CaptureKey (wxKeyEvent &event, ViewInfo &viewInfo, wxWindow *pParent) override
unsigned KeyDown (wxKeyEvent &event, ViewInfo &viewInfo, wxWindow *pParent) override
unsigned Char (wxKeyEvent &event, ViewInfo &viewInfo, wxWindow *pParent) override
void SetOffset (double dOffset) override
void Draw (TrackPanelDrawingContext &context, const wxRect &r, const SelectedRegion &selectedRegion, const ZoomInfo &zoomInfo) const
int getSelectedIndex () const
int GetKind () const override
double GetOffset () const override
double GetStartTime () const override
double GetEndTime () const override
Track::Holder Duplicate () const override
void SetSelected (bool s) override
bool HandleXMLTag (const wxChar *tag, const wxChar **attrs) override
XMLTagHandlerHandleXMLChild (const wxChar *tag) override
void WriteXML (XMLWriter &xmlFile) const override
Track::Holder Cut (double t0, double t1) override
Track::Holder Copy (double t0, double t1, bool forClipboard=true) const override
void Clear (double t0, double t1) override
void Paste (double t, const Track *src) override
bool Repeat (double t0, double t1, int n)
void Silence (double t0, double t1) override
void InsertSilence (double t, double len) override
void OverGlyph (LabelTrackHit &hit, int x, int y) const
void ResetFlags ()
Flags SaveFlags () const
void RestoreFlags (const Flags &flags)
int OverATextBox (int xx, int yy) const
bool OverTextBox (const LabelStruct *pLabel, int x, int y) const
bool CutSelectedText ()
bool CopySelectedText ()
bool PasteSelectedText (double sel0, double sel1)
void HandleGlyphClick (LabelTrackHit &hit, const wxMouseEvent &evt, const wxRect &r, const ZoomInfo &zoomInfo, SelectedRegion *newSel)
void HandleTextClick (const wxMouseEvent &evt, const wxRect &r, const ZoomInfo &zoomInfo, SelectedRegion *newSel)
bool HandleGlyphDragRelease (LabelTrackHit &hit, const wxMouseEvent &evt, wxRect &r, const ZoomInfo &zoomInfo, SelectedRegion *newSel)
void HandleTextDragRelease (const wxMouseEvent &evt)
bool OnKeyDown (SelectedRegion &sel, wxKeyEvent &event)
 KeyEvent is called for every keypress when over the label track. More...
bool OnChar (SelectedRegion &sel, wxKeyEvent &event)
void Import (wxTextFile &f)
 Import labels, handling files with or without end-times. More...
void Export (wxTextFile &f) const
 Export labels including label start and end-times. More...
void Unselect ()
bool IsSelected () const
int GetNumLabels () const
const LabelStructGetLabel (int index) const
int AddLabel (const SelectedRegion &region, const wxString &title=wxT(""), int restoreFocus=-1)
int GetLabelIndex (double t, double t1)
void DeleteLabel (int index)
bool CalcCursorX (int *x) const
void CalcHighlightXs (int *x1, int *x2) const
void MayAdjustLabel (LabelTrackHit &hit, int iLabel, int iEdge, bool bAllowSwapping, double fNewTime)
void MayMoveLabel (int iLabel, int iEdge, double fNewTime)
bool PasteOver (double t, const Track *src)
void ShiftLabelsOnInsert (double length, double pt)
void ChangeLabelsOnReverse (double b, double e)
void ScaleLabels (double b, double e, double change)
double AdjustTimeStampOnScale (double t, double b, double e, double change)
void WarpLabels (const TimeWarper &warper)
wxString GetTextOfLabels (double t0, double t1) const
int FindNextLabel (const SelectedRegion &currentSelection)
int FindPrevLabel (const SelectedRegion &currentSelection)
void SortLabels (LabelTrackHit *pHit=nullptr)
int FindCurrentCursorPosition (int xPos)
void SetCurrentCursorPosition (int xPos)
 Set the cursor position according to x position of mouse. More...
- Public Member Functions inherited from Track
std::vector< UIHandlePtrHitTest (const TrackPanelMouseState &, const AudacityProject *pProject) finaloverride
std::shared_ptr< TrackPanelCellGetTrackControl ()
std::shared_ptr< TrackPanelCellGetVRulerControl ()
std::shared_ptr< TrackPanelCellGetResizer ()
virtual int GetMinimizedHeight () const
int GetActualHeight () const
int GetIndex () const
void SetIndex (int index)
int GetY () const
void SetY (int y)
int GetHeight () const
virtual void SetHeight (int h)
bool GetMinimized () const
void SetMinimized (bool isMinimized)
TrackGetLink () const
 Track (const std::shared_ptr< DirManager > &projDirManager)
 Track (const Track &orig)
virtual ~Track ()
void Init (const Track &orig)
virtual void Merge (const Track &orig)
wxString GetName () const
void SetName (const wxString &n)
wxString GetDefaultName () const
void SetDefaultName (const wxString &n)
bool GetSelected () const
bool GetLinked () const
void SetLinked (bool l)
virtual int GetChannel () const
void Offset (double t)
void SetChannel (int c)
virtual void SetPan (float)
virtual void SetPanFromChannelType ()
const std::shared_ptr
< DirManager > & 
GetDirManager () const
virtual Holder Cut (double WXUNUSED(t0), double WXUNUSED(t1))=0
virtual Holder Copy (double WXUNUSED(t0), double WXUNUSED(t1), bool forClipboard=true) const =0
virtual void Clear (double WXUNUSED(t0), double WXUNUSED(t1))=0
virtual void Paste (double WXUNUSED(t), const Track *WXUNUSED(src))=0
virtual void SyncLockAdjust (double oldT1, double newT1)
virtual void Silence (double WXUNUSED(t0), double WXUNUSED(t1))=0
virtual void InsertSilence (double WXUNUSED(t), double WXUNUSED(len))=0
virtual bool GetErrorOpening ()
bool IsSyncLockSelected () const
- Public Member Functions inherited from CommonTrackPanelCell
 CommonTrackPanelCell ()
virtual ~CommonTrackPanelCell ()=0
- Public Member Functions inherited from TrackPanelCell
virtual ~TrackPanelCell ()=0
virtual unsigned DoContextMenu (const wxRect &rect, wxWindow *pParent, wxPoint *pPosition)
virtual unsigned KeyUp (wxKeyEvent &event, ViewInfo &viewInfo, wxWindow *pParent)
- Public Member Functions inherited from XMLTagHandler
 XMLTagHandler ()
virtual ~XMLTagHandler ()
virtual void HandleXMLEndTag (const wxChar *WXUNUSED(tag))
virtual void HandleXMLContent (const wxString &WXUNUSED(content))
bool ReadXMLTag (const char *tag, const char **attrs)
void ReadXMLEndTag (const char *tag)
void ReadXMLContent (const char *s, int len)
XMLTagHandlerReadXMLChild (const char *tag)

Static Public Member Functions

static wxFont GetFont (const wxString &faceName, int size=DefaultFontSize)
static void ResetFont ()
static wxBitmap & GetGlyph (int i)
static bool IsTextClipSupported ()
- Static Public Member Functions inherited from Track
template<typename Subclass = Track>
static std::shared_ptr< Subclass > Pointer (Track *t)
template<typename Subclass = const Track>
static std::shared_ptr< Subclass > Pointer (const Track *t)

Static Public Attributes

static const int DefaultFontSize = 12

Protected Member Functions

std::shared_ptr< TrackControlsGetControls () override
< TrackVRulerControls
GetVRulerControls () override
- Protected Member Functions inherited from Track
std::shared_ptr< TrackFindTrack () override
- Protected Member Functions inherited from CommonTrackPanelCell
unsigned HandleWheelRotation (const TrackPanelMouseEvent &event, AudacityProject *pProject) override

Private Member Functions

void ShowContextMenu ()
void OnContextMenu (wxCommandEvent &evt)
void ComputeLayout (const wxRect &r, const ZoomInfo &zoomInfo) const
void ComputeTextPosition (const wxRect &r, int index) const
void calculateFontHeight (wxDC &dc) const
void RemoveSelectedText ()

Private Attributes

int mSelIndex
int mxMouseDisplacement
 Keeps track of the currently selected label. More...
LabelArray mLabels
 Displacement of mouse cursor from the centre being dragged. More...
int mCurrentCursorPos
int mInitialCursorPos
 current cursor position More...
bool mRightDragging
 initial cursor position More...
bool mDrawCursor
 flag to tell if it's a valid dragging More...
int mRestoreFocus
 cursor or not More...
double mClipLen
 when done editing More...
int miLastLabel
std::weak_ptr< LabelGlyphHandlemGlyphHandle
std::weak_ptr< LabelTextHandlemTextHandle

Static Private Attributes

static int mIconHeight
static int mIconWidth
static int mTextHeight
static bool mbGlyphsReady =false
static wxBitmap mBoundaryGlyphs [NUM_GLYPH_CONFIGS *NUM_GLYPH_HIGHLIGHTS]
static int mFontHeight =-1
static wxFont msFont


class LabelStruct

Additional Inherited Members

- Public Attributes inherited from Track
wxSize vrulerSize
- Protected Attributes inherited from Track
std::weak_ptr< TrackListmList
TrackNodePointer mNode {}
int mIndex
int mY
int mHeight
wxString mName
wxString mDefaultName
bool mSelected
bool mLinked
bool mMinimized
int mChannel
double mOffset
std::shared_ptr< DirManagermDirManager
std::shared_ptr< TrackControlsmpControls
< TrackVRulerControls
< TrackPanelResizerCell
std::weak_ptr< SelectHandlemSelectHandle
std::weak_ptr< TimeShiftHandlemTimeShiftHandle

Detailed Description

A LabelTrack is a Track that holds labels (LabelStruct).

These are used to annotate a waveform. Each label has a start time and an end time. The text of the labels is editable and the positions of the end points are draggable.

Member Typedef Documentation

using LabelTrack::Holder = std::unique_ptr<LabelTrack>

Constructor & Destructor Documentation

LabelTrack::LabelTrack ( const std::shared_ptr< DirManager > &  projDirManager)
LabelTrack::LabelTrack ( const LabelTrack orig)
LabelTrack::~LabelTrack ( )

Member Function Documentation

int LabelTrack::AddLabel ( const SelectedRegion region,
const wxString &  title = wxT(""),
int  restoreFocus = -1 
double LabelTrack::AdjustTimeStampOnScale ( double  t,
double  b,
double  e,
double  change 

Referenced by ScaleLabels().

bool LabelTrack::CalcCursorX ( int *  x) const
void LabelTrack::CalcHighlightXs ( int *  x1,
int *  x2 
) const
void LabelTrack::calculateFontHeight ( wxDC &  dc) const

References mFontHeight.

unsigned LabelTrack::CaptureKey ( wxKeyEvent &  event,
ViewInfo viewInfo,
wxWindow *  pParent 

Reimplemented from TrackPanelCell.

References DoCaptureKey(), and RefreshCode::RefreshNone.

void LabelTrack::ChangeLabelsOnReverse ( double  b,
double  e 
unsigned LabelTrack::Char ( wxKeyEvent &  event,
ViewInfo viewInfo,
wxWindow *  pParent 
void LabelTrack::Clear ( double  t0,
double  t1 
void LabelTrack::ComputeLayout ( const wxRect &  r,
const ZoomInfo zoomInfo 
) const

ComputeLayout determines which row each label should be placed on, and reserves space for it. Function assumes that the labels are sorted.

References ComputeTextPosition(), MAX_NUM_ROWS, mIconHeight, mIconWidth, mLabels, mTextHeight, and ZoomInfo::TimeToPosition().

void LabelTrack::ComputeTextPosition ( const wxRect &  r,
int  index 
) const

ComputeTextPosition is 'smart' about where to display the label text.

The text must be displayed between its endpoints x and x1 We'd also like it centered between them, and we'd like it on screen. It isn't always possible to achieve all of this, so we do the best we can.

This function has a number of tests and adjustments to the text start position. The tests later in the function will take priority over the ones earlier, so because centering is the first thing we do, it's the first thing we lose if we can't do everything we want to.

References mIconWidth, and mLabels.

Referenced by ComputeLayout().

bool LabelTrack::CopySelectedText ( )

Copy the selected text in the text box

true if text is selected in text box, false otherwise

References mCurrentCursorPos, mInitialCursorPos, mLabels, mSelIndex, and safenew.

Referenced by HandleTextDragRelease(), and OnContextMenu().

void LabelTrack::CreateCustomGlyphs ( )

CreateCustomGlyphs() creates the mBoundaryGlyph array. It's a bit like painting by numbers!

Schematically the glyphs we want will 'look like': <O, O> and <O> for a left boundary to a label, a right boundary and both. we're creating all three glyphs using the one Xpm Spec.

When we hover over a glyph we highlight the inside of either the '<', the 'O' or the '>' or none, giving 3 x 4 = 12 combinations.

Two of those combinations aren't used, but treating them specially would make other code more complicated.

References GlyphXpmRegionSpec, mbGlyphsReady, mBoundaryGlyphs, mIconHeight, mIconWidth, mTextHeight, NUM_GLYPH_CONFIGS, NUM_GLYPH_HIGHLIGHTS, and safenew.

Referenced by LabelTrack().

Track::Holder LabelTrack::Cut ( double  t0,
double  t1 

References Clear(), and Copy().

bool LabelTrack::CutSelectedText ( )

Cut the selected text in the text box

true if text is selected in text box, false otherwise

References IsTextSelected(), mCurrentCursorPos, mInitialCursorPos, mLabels, mSelIndex, and safenew.

Referenced by OnContextMenu().

void LabelTrack::DeleteLabel ( int  index)
std::vector< UIHandlePtr > LabelTrack::DetailedHitTest ( const TrackPanelMouseState state,
const AudacityProject pProject,
int  currentTool,
bool  bMultiTool 
Track::Holder LabelTrack::Duplicate ( ) const

Implements Track.

void LabelTrack::Export ( wxTextFile &  f) const

Export labels including label start and end-times.

References mLabels.

int LabelTrack::FindCurrentCursorPosition ( int  xPos)

uses GetTextExtent to find the character position corresponding to the x pixel position.

References mLabels, mSelIndex, and msFont.

Referenced by HandleTextClick(), and SetCurrentCursorPosition().

int LabelTrack::FindNextLabel ( const SelectedRegion currentSelection)
int LabelTrack::FindPrevLabel ( const SelectedRegion currentSelection)
std::shared_ptr< TrackControls > LabelTrack::GetControls ( )

Implements Track.

References Track::Pointer().

double LabelTrack::GetEndTime ( ) const
wxFont LabelTrack::GetFont ( const wxString &  faceName,
int  size = DefaultFontSize 
wxBitmap & LabelTrack::GetGlyph ( int  i)

References ThemeBase::Bitmap(), and theTheme.

Referenced by LabelStruct::DrawGlyphs().

int LabelTrack::GetKind ( ) const

Reimplemented from Track.

References Track::Label.

int LabelTrack::GetLabelIndex ( double  t,
double  t1 

Referenced by DoCaptureKey(), and OnContextMenu().

double LabelTrack::GetOffset ( ) const

Implements Track.

References Track::mOffset.

int LabelTrack::getSelectedIndex ( ) const
double LabelTrack::GetStartTime ( ) const
wxString LabelTrack::GetTextOfLabels ( double  t0,
double  t1 
) const
std::shared_ptr< TrackVRulerControls > LabelTrack::GetVRulerControls ( )

Implements Track.

References Track::Pointer().

void LabelTrack::HandleGlyphClick ( LabelTrackHit hit,
const wxMouseEvent &  evt,
const wxRect &  r,
const ZoomInfo zoomInfo,
SelectedRegion newSel 
bool LabelTrack::HandleGlyphDragRelease ( LabelTrackHit hit,
const wxMouseEvent &  evt,
wxRect &  r,
const ZoomInfo zoomInfo,
SelectedRegion newSel 
void LabelTrack::HandleTextDragRelease ( const wxMouseEvent &  evt)
XMLTagHandler * LabelTrack::HandleXMLChild ( const wxChar *  tag)

Implements XMLTagHandler.

bool LabelTrack::HandleXMLTag ( const wxChar *  tag,
const wxChar **  attrs 
void LabelTrack::Import ( wxTextFile &  f)

Import labels, handling files with or without end-times.

References _(), LabelStruct::Import(), mLabels, and SortLabels().

void LabelTrack::InsertSilence ( double  t,
double  len 
bool LabelTrack::IsGoodLabelEditKey ( const wxKeyEvent &  evt)

This returns true for keys we capture for label editing.

Referenced by DoCaptureKey(), and OnKeyDown().

bool LabelTrack::IsGoodLabelFirstKey ( const wxKeyEvent &  evt)

Returns true for keys we capture to start a label.

Referenced by DoCaptureKey(), and OnKeyDown().

bool LabelTrack::IsSelected ( ) const

References mLabels, and mSelIndex.

Referenced by AudacityProject::HandlePasteText().

bool LabelTrack::IsTextClipSupported ( )
true if the text data is available in the clipboard, false otherwise

Referenced by PasteSelectedText(), and ShowContextMenu().

bool LabelTrack::IsTextSelected ( )
void LabelTrack::MayAdjustLabel ( LabelTrackHit hit,
int  iLabel,
int  iEdge,
bool  bAllowSwapping,
double  fNewTime 

If the index is for a real label, adjust its left or right boundary. - index of label, -1 for none. - which edge is requested to move, -1 for left +1 for right. - if we can switch which edge is being dragged. fNewTime - the NEW time for this edge of the label.

References LabelStruct::AdjustEdge(), LabelTrackHit::mMouseOverLabelLeft, and LabelTrackHit::mMouseOverLabelRight.

void LabelTrack::MayMoveLabel ( int  iLabel,
int  iEdge,
double  fNewTime 

References mLabels.

bool LabelTrack::OnChar ( SelectedRegion sel,
wxKeyEvent &  event 

OnChar is called for incoming characters – that's any keypress not handled by OnKeyDown.

References _(), AddLabel(), GetActiveProject(), mCurrentCursorPos, mDrawCursor, mInitialCursorPos, mLabels, mSelIndex, AudacityProject::mViewInfo, AudacityProject::PushState(), RemoveSelectedText(), ViewInfo::selectedRegion, and SetSelected().

Referenced by Char().

void LabelTrack::OnContextMenu ( wxCommandEvent &  evt)

Cut selected text if cut menu item is selected

Copy selected text if copy menu item is selected

paste selected text if paste menu item is selected

DELETE selected label

References _(), CONSOLIDATE, CopySelectedText(), CutSelectedText(), DeleteLabel(), AudacityProject::DoEditLabels(), GetActiveProject(), GetLabelIndex(), AudacityProject::GetSel0(), AudacityProject::GetSel1(), OnCopySelectedTextID, OnCutSelectedTextID, OnDeleteSelectedLabelID, OnEditSelectedLabelID, OnPasteSelectedTextID, PasteSelectedText(), and AudacityProject::PushState().

Referenced by ShowContextMenu().

int LabelTrack::OverATextBox ( int  xx,
int  yy 
) const

References mLabels, and OverTextBox().

Referenced by HandleTextClick().

void LabelTrack::OverGlyph ( LabelTrackHit hit,
int  x,
int  y 
) const

TODO: Investigate what happens with large numbers of labels, might need a binary search rather than a linear one.

References LabelTrackHit::mEdge, mLabels, LabelTrackHit::mMouseOverLabelLeft, LabelTrackHit::mMouseOverLabelRight, mTextHeight, and OverTextBox().

bool LabelTrack::OverTextBox ( const LabelStruct pLabel,
int  x,
int  y 
) const
void LabelTrack::Paste ( double  t,
const Track src 
bool LabelTrack::PasteOver ( double  t,
const Track src 
bool LabelTrack::PasteSelectedText ( double  sel0,
double  sel1 

Paste the text on the clipboard to text box

true if mouse is clicked in text box, false otherwise

References AddLabel(), IsTextClipSupported(), mCurrentCursorPos, mInitialCursorPos, mLabels, and mSelIndex.

Referenced by AudacityProject::HandlePasteText(), HandleTextClick(), OnContextMenu(), and AudacityProject::OnPasteNewLabel().

void LabelTrack::RemoveSelectedText ( )

References mCurrentCursorPos, mInitialCursorPos, mLabels, and mSelIndex.

Referenced by OnChar(), and OnKeyDown().

void LabelTrack::ResetFlags ( )
void LabelTrack::ResetFont ( )
Flags LabelTrack::SaveFlags ( ) const
void LabelTrack::ScaleLabels ( double  b,
double  e,
double  change 
void LabelTrack::SetCurrentCursorPosition ( int  xPos)

Set the cursor position according to x position of mouse.

References FindCurrentCursorPosition(), and mCurrentCursorPos.

Referenced by HandleTextDragRelease().

void LabelTrack::SetOffset ( double  dOffset)

Reimplemented from Track.

References mLabels.

Referenced by Effect::ModifiedAnalysisTrack::ModifiedAnalysisTrack().

void LabelTrack::SetSelected ( bool  s)

Reimplemented from Track.

References Track::SetSelected(), and Unselect().

Referenced by AudacityProject::DoAddLabel(), HandleXMLTag(), and OnChar().

void LabelTrack::ShiftLabelsOnInsert ( double  length,
double  pt 
void LabelTrack::SortLabels ( LabelTrackHit pHit = nullptr)

Sorts the labels in order of their starting times. This function is called often (whilst dragging a label) We expect them to be very nearly in order, so insertion sort (with a linear search) is a reasonable choice.

References LabelTrackHit::mMouseOverLabelLeft, LabelTrackHit::mMouseOverLabelRight, and mSelIndex.

Referenced by ChangeLabelsOnReverse(), Import(), Silence(), and WarpLabels().

void LabelTrack::Unselect ( )
void LabelTrack::WarpLabels ( const TimeWarper warper)
void LabelTrack::WriteXML ( XMLWriter xmlFile) const

Implements Track.

Friends And Related Function Documentation

friend class LabelStruct

Member Data Documentation

const int LabelTrack::DefaultFontSize = 12
bool LabelTrack::mbGlyphsReady =false

Referenced by CreateCustomGlyphs().

wxBitmap LabelTrack::mBoundaryGlyphs

We have several variants of the icons (highlighting). The icons are draggable, and you can drag one boundary or all boundaries at the same timecode depending on whether you click the centre (for all) or the arrow part (for one). Currently we have twelve variants but we're only using six.

Referenced by CreateCustomGlyphs().

double LabelTrack::mClipLen

when done editing

Restore focus to this track

Referenced by Paste().

bool LabelTrack::mDrawCursor

flag to tell if it's a valid dragging

Referenced by AddLabel(), HandleTextClick(), OnChar(), OnKeyDown(), ResetFlags(), and RestoreFlags().

int LabelTrack::mFontHeight =-1
std::weak_ptr<LabelGlyphHandle> LabelTrack::mGlyphHandle
int LabelTrack::miLastLabel

Referenced by FindNextLabel(), and FindPrevLabel().

int LabelTrack::mRestoreFocus

cursor or not

flag to tell if drawing the

Referenced by AddLabel(), and OnKeyDown().

bool LabelTrack::mRightDragging

initial cursor position

Referenced by HandleTextClick(), HandleTextDragRelease(), ResetFlags(), and RestoreFlags().

wxFont LabelTrack::msFont
std::weak_ptr<LabelTextHandle> LabelTrack::mTextHandle
int LabelTrack::mxMouseDisplacement

Keeps track of the currently selected label.

The documentation for this class was generated from the following files: