Difference between revisions of "Withdrawn: Proposal Rename "Snap To""

From Audacity Wiki
Jump to: navigation, search
(search all instances of "Snap To" in source code)
(more code details; additional image)
Line 43: Line 43:
 
   Matching lines: 5    Matching files: 3    Total files searched: 792
 
   Matching lines: 5    Matching files: 3    Total files searched: 792
  
It looks like we should change all five of these.
+
It looks like we should change all five of these. There are also numerous instances of "SnapTo…" in variable and function names (mSnapTo, OnSnapToID, OnSnapToOn etc.); thefor future code maintainability it makes sense to change these as well (with one exception:
 +
gPrefs->Read(wxT("/SnapTo"), 0L)
 +
for backwards compatibility I would keep the preferences setting variable name and just comment the code). It looks like there are about 60 lines that this would affect:
 +
Find all "SnapTo", Match case, Subfolders, Find Results 1, "Entire Solution", "*.cpp;*.h"
 +
  src\Menus.cpp(1577):  c->AddCommand(wxT("SnapToOn"), _("Time Snap On"), FN(OnSnapToOn));
 +
  src\Menus.cpp(1578):  c->AddCommand(wxT("SnapToOff"), _("Time Snap Off"), FN(OnSnapToOff));
 +
  src\Menus.cpp(6598):void AudacityProject::OnSnapToOn()
 +
  src\Menus.cpp(6600):  SetSnapTo(true);
 +
  src\Menus.cpp(6603):void AudacityProject::OnSnapToOff()
 +
  src\Menus.cpp(6605):  SetSnapTo(false);
 +
  src\Menus.h(168):void OnSnapToOn();
 +
  src\Menus.h(169):void OnSnapToOff();
 +
  src\Project.cpp(728):    mSnapTo(0),
 +
  src\Project.cpp(1054):  SetSnapTo(gPrefs->Read(wxT("/SnapTo"), 0L)!=0);
 +
  src\Project.cpp(1187):void AudacityProject::AS_SetSnapTo(bool state)
 +
  src\Project.cpp(1189):  SetSnapTo(state);
 +
  src\Project.cpp(1193):bool AudacityProject::AS_GetSnapTo()
 +
  src\Project.cpp(1195):  return GetSnapTo();
 +
  src\Project.cpp(4598):void AudacityProject::SetSnapTo(bool state)
 +
  src\Project.cpp(4600):  mSnapTo = state;
 +
  src\Project.cpp(4601):  mCommandManager.Check(wxT("Snap"), mSnapTo);
 +
  src\Project.cpp(4602):  gPrefs->Write(wxT("/SnapTo"), mSnapTo);
 +
  src\Project.cpp(4606):      GetSelectionBar()->SetSnapTo(state);
 +
  src\Project.cpp(4610):bool AudacityProject::GetSnapTo()
 +
  src\Project.cpp(4612):  return mSnapTo;
 +
  src\Project.h(311):  void SetSnapTo(bool state);
 +
  src\Project.h(312):  bool GetSnapTo();
 +
  src\Project.h(370):  virtual void AS_SetSnapTo(bool state);
 +
  src\Project.h(371):  virtual bool AS_GetSnapTo();
 +
  src\Project.h(445):  bool mSnapTo;
 +
  src\Snap.cpp(32):  mSnapToTime = false;
 +
  src\Snap.cpp(41):  if (gPrefs->Read(wxT("/SnapTo"), 0L) != 0L && !noTimeSnap)
 +
  src\Snap.cpp(46):        mSnapToTime = true;
 +
  src\Snap.cpp(180):bool SnapManager::SnapToPoints(Track *currentTrack,
 +
  src\Snap.cpp(252):  *snappedPoint = SnapToPoints(currentTrack, t, rightEdge, out_t);
 +
  src\Snap.cpp(256):  if (mSnapToTime) {
 +
  src\Snap.h(65):  bool SnapToPoints(Track *currentTrack, double t, bool rightEdge,
 +
  src\Snap.h(74):  bool            mSnapToTime;
 +
  src\TrackPanel.cpp(6264):  bool snapToTime = (gPrefs->Read(wxT("/SnapTo"), 0L) != 0);
 +
  src\TrackPanel.cpp(6373):  bool snapToTime = (gPrefs->Read(wxT("/SnapTo"), 0L) != 0);
 +
  src\TrackPanel.h(225):  //virtual void SetSnapTo(int snapto)
 +
  src\TrackPanel.h(565):  // and SlideSnapToPoints gets populated with the start and stop times
 +
  src\TrackPanel.h(570):  wxBaseArrayDouble mSlideSnapToPoints;
 +
  src\toolbars\SelectionBar.cpp(65):  OnSnapToID,
 +
  src\toolbars\SelectionBar.cpp(78):  EVT_CHECKBOX(OnSnapToID, SelectionBar::OnSnapTo)
 +
  src\toolbars\SelectionBar.cpp(233):  mSnapTo = new wxCheckBox(this, OnSnapToID, _("Time Snap"),
 +
  src\toolbars\SelectionBar.cpp(236):  mainSizer->Add(mSnapTo,
 +
  src\toolbars\SelectionBar.cpp(238):  mSnapTo->SetName(_("Time Snap"));
 +
  src\toolbars\SelectionBar.cpp(239):  mSnapTo->SetValue(gPrefs->Read(wxT("/SnapTo"), 0L)!=0);
 +
  src\toolbars\SelectionBar.cpp(241):      mSnapTo->SetToolTip(wxString::Format(_("Snap Clicks/Selections to %s"), formatName.c_str()));
 +
  src\toolbars\SelectionBar.cpp(244):  mSnapTo->Connect(wxEVT_SET_FOCUS,
 +
  src\toolbars\SelectionBar.cpp(248):  mSnapTo->Connect(wxEVT_KILL_FOCUS,
 +
  src\toolbars\SelectionBar.cpp(372):      mSnapTo->SetToolTip(wxString::Format(_("Snap Clicks/Selections to %s"), formatName.c_str()));
 +
  src\toolbars\SelectionBar.cpp(468):void SelectionBar::SetSnapTo(bool state)
 +
  src\toolbars\SelectionBar.cpp(470):  mSnapTo->SetValue(state);
 +
  src\toolbars\SelectionBar.cpp(529):  // Pass the SPACE through for SnapTo
 +
  src\toolbars\SelectionBar.cpp(530):  if (w == mSnapTo && keyCode == WXK_SPACE) {
 +
  src\toolbars\SelectionBar.cpp(562):void SelectionBar::OnSnapTo(wxCommandEvent & event)
 +
  src\toolbars\SelectionBar.cpp(564):  mListener->AS_SetSnapTo(mSnapTo->GetValue());
 +
  src\toolbars\SelectionBar.h(37):  virtual bool AS_GetSnapTo() = 0;
 +
  src\toolbars\SelectionBar.h(38):  virtual void AS_SetSnapTo(bool state) = 0;
 +
  src\toolbars\SelectionBar.h(59):  void SetSnapTo(bool state);
 +
  src\toolbars\SelectionBar.h(75):  void OnSnapTo(wxCommandEvent & event);
 +
  src\toolbars\SelectionBar.h(98):  wxCheckBox    *mSnapTo;
 +
  Matching lines: 60    Matching files: 10    Total files searched: 792
  
  
Line 51: Line 115:
 
Steve's Selection Toolbar mockup
 
Steve's Selection Toolbar mockup
 
:[[File:Steve's Selection Toolbar mockup.png]]
 
:[[File:Steve's Selection Toolbar mockup.png]]
 +
using "Time Snap" Selection Toolbar
 +
:[[File:Ts.png]]
  
 
==Previous Feature Requests relating to this proposal==
 
==Previous Feature Requests relating to this proposal==

Revision as of 16:50, 30 April 2013

Proposal pages help us get from feature requests into actual plans. This page is a proposal to rename the "Snap To" function
Proposal pages are used on an ongoing basis by the Audacity development team and are open to edits from visitors to the wiki. They are a good way to get community feedback on a proposal.


  • Note: Proposals for Google Summer of Code projects are significantly different in structure, are submitted via Google's web app and may or may not have a corresponding proposal page.
Peter 20Apr13: ToDo-2 Ready for editorial review, merciless editing and voting.

The Problem

We have two different "Snap To " functions in Audacity

  1. Time format snapping - currently identified as "Snap To" in Audacity
  2. Location snapping - currently identified as "Snap-to Guides" in the 2.0.3 Manual, but renamed to "Boundary Snap Guides" in the 2.0.4 alpha Manual.

The revised nomenclature for the location snapping was introduced in the 2.0.4 Manual as an attempt to provide some differentiation, however there is still room in the Manual (and in the perceptions of users) for confusion between to two distinct types of snapping in Audacity.


Proposed Feature

Following discussions on the Manual email list Gale has proposed that we rename "Snap To" (the time format snapping) to "Time Snap".

Gale wrote: " ... any name change should be as unambiguous as possible."

Alternative nomenclature suggestions

Peter's original suggestion was "Align With".

  • I now withdraw that as I believe any changed nomenclature should contain the word "Snap".

Steve suggested "Selection Snap" (and moving the snap to the right end of the Selection Toolbar).

  • Gale: -1


Developer/QA Backing

  • Peter: +1 for "Time Snap"
  • Gale: +1 for "Time Snap"
  • Steve

Use Cases

Not relevant.


Details

Making this change should involve only a simple rename of the display in the GUI and some straightforward update work in the Manual.

Find all "Snap To", Match case, Whole word, Subfolders, Find Results 1, "Entire Solution", "*.cpp;*.h"

 src\Menus.cpp(1577): c->AddCommand(wxT("SnapToOn"), _("Snap To On"), FN(OnSnapToOn));
 src\Menus.cpp(1578): c->AddCommand(wxT("SnapToOff"), _("Snap To Off"), FN(OnSnapToOff));
 src\Project.h(309): // Snap To
 src\toolbars\SelectionBar.cpp(233): mSnapTo = new wxCheckBox(this, OnSnapToID, _("Snap To"),
 src\toolbars\SelectionBar.cpp(238): mSnapTo->SetName(_("Snap To"));
 Matching lines: 5    Matching files: 3    Total files searched: 792

It looks like we should change all five of these. There are also numerous instances of "SnapTo…" in variable and function names (mSnapTo, OnSnapToID, OnSnapToOn etc.); thefor future code maintainability it makes sense to change these as well (with one exception: gPrefs->Read(wxT("/SnapTo"), 0L) for backwards compatibility I would keep the preferences setting variable name and just comment the code). It looks like there are about 60 lines that this would affect: Find all "SnapTo", Match case, Subfolders, Find Results 1, "Entire Solution", "*.cpp;*.h"

 src\Menus.cpp(1577):   c->AddCommand(wxT("SnapToOn"), _("Time Snap On"), FN(OnSnapToOn));
 src\Menus.cpp(1578):   c->AddCommand(wxT("SnapToOff"), _("Time Snap Off"), FN(OnSnapToOff));
 src\Menus.cpp(6598):void AudacityProject::OnSnapToOn()
 src\Menus.cpp(6600):   SetSnapTo(true);
 src\Menus.cpp(6603):void AudacityProject::OnSnapToOff()
 src\Menus.cpp(6605):   SetSnapTo(false);
 src\Menus.h(168):void OnSnapToOn();
 src\Menus.h(169):void OnSnapToOff();
 src\Project.cpp(728):     mSnapTo(0),
 src\Project.cpp(1054):   SetSnapTo(gPrefs->Read(wxT("/SnapTo"), 0L)!=0);
 src\Project.cpp(1187):void AudacityProject::AS_SetSnapTo(bool state)
 src\Project.cpp(1189):   SetSnapTo(state);
 src\Project.cpp(1193):bool AudacityProject::AS_GetSnapTo()
 src\Project.cpp(1195):   return GetSnapTo();
 src\Project.cpp(4598):void AudacityProject::SetSnapTo(bool state)
 src\Project.cpp(4600):   mSnapTo = state;
 src\Project.cpp(4601):   mCommandManager.Check(wxT("Snap"), mSnapTo);
 src\Project.cpp(4602):   gPrefs->Write(wxT("/SnapTo"), mSnapTo);
 src\Project.cpp(4606):      GetSelectionBar()->SetSnapTo(state);
 src\Project.cpp(4610):bool AudacityProject::GetSnapTo()
 src\Project.cpp(4612):   return mSnapTo;
 src\Project.h(311):   void SetSnapTo(bool state);
 src\Project.h(312):   bool GetSnapTo();
 src\Project.h(370):   virtual void AS_SetSnapTo(bool state);
 src\Project.h(371):   virtual bool AS_GetSnapTo();
 src\Project.h(445):   bool mSnapTo;
 src\Snap.cpp(32):   mSnapToTime = false;
 src\Snap.cpp(41):   if (gPrefs->Read(wxT("/SnapTo"), 0L) != 0L && !noTimeSnap)
 src\Snap.cpp(46):         mSnapToTime = true;
 src\Snap.cpp(180):bool SnapManager::SnapToPoints(Track *currentTrack,
 src\Snap.cpp(252):   *snappedPoint = SnapToPoints(currentTrack, t, rightEdge, out_t);
 src\Snap.cpp(256):   if (mSnapToTime) {
 src\Snap.h(65):   bool SnapToPoints(Track *currentTrack, double t, bool rightEdge,
 src\Snap.h(74):   bool             mSnapToTime;
 src\TrackPanel.cpp(6264):   bool snapToTime = (gPrefs->Read(wxT("/SnapTo"), 0L) != 0);
 src\TrackPanel.cpp(6373):   bool snapToTime = (gPrefs->Read(wxT("/SnapTo"), 0L) != 0);
 src\TrackPanel.h(225):   //virtual void SetSnapTo(int snapto)
 src\TrackPanel.h(565):   // and SlideSnapToPoints gets populated with the start and stop times
 src\TrackPanel.h(570):   wxBaseArrayDouble mSlideSnapToPoints;
 src\toolbars\SelectionBar.cpp(65):   OnSnapToID,
 src\toolbars\SelectionBar.cpp(78):   EVT_CHECKBOX(OnSnapToID, SelectionBar::OnSnapTo)
 src\toolbars\SelectionBar.cpp(233):   mSnapTo = new wxCheckBox(this, OnSnapToID, _("Time Snap"),
 src\toolbars\SelectionBar.cpp(236):   mainSizer->Add(mSnapTo,
 src\toolbars\SelectionBar.cpp(238):   mSnapTo->SetName(_("Time Snap"));
 src\toolbars\SelectionBar.cpp(239):   mSnapTo->SetValue(gPrefs->Read(wxT("/SnapTo"), 0L)!=0);
 src\toolbars\SelectionBar.cpp(241):      mSnapTo->SetToolTip(wxString::Format(_("Snap Clicks/Selections to %s"), formatName.c_str()));
 src\toolbars\SelectionBar.cpp(244):   mSnapTo->Connect(wxEVT_SET_FOCUS,
 src\toolbars\SelectionBar.cpp(248):   mSnapTo->Connect(wxEVT_KILL_FOCUS,
 src\toolbars\SelectionBar.cpp(372):      mSnapTo->SetToolTip(wxString::Format(_("Snap Clicks/Selections to %s"), formatName.c_str()));
 src\toolbars\SelectionBar.cpp(468):void SelectionBar::SetSnapTo(bool state)
 src\toolbars\SelectionBar.cpp(470):   mSnapTo->SetValue(state);
 src\toolbars\SelectionBar.cpp(529):   // Pass the SPACE through for SnapTo
 src\toolbars\SelectionBar.cpp(530):   if (w == mSnapTo && keyCode == WXK_SPACE) {
 src\toolbars\SelectionBar.cpp(562):void SelectionBar::OnSnapTo(wxCommandEvent & event)
 src\toolbars\SelectionBar.cpp(564):   mListener->AS_SetSnapTo(mSnapTo->GetValue());
 src\toolbars\SelectionBar.h(37):   virtual bool AS_GetSnapTo() = 0;
 src\toolbars\SelectionBar.h(38):   virtual void AS_SetSnapTo(bool state) = 0;
 src\toolbars\SelectionBar.h(59):   void SetSnapTo(bool state);
 src\toolbars\SelectionBar.h(75):   void OnSnapTo(wxCommandEvent & event);
 src\toolbars\SelectionBar.h(98):   wxCheckBox     *mSnapTo;
 Matching lines: 60    Matching files: 10    Total files searched: 792


The tooltip would not need to be changed as the current text is equally relevant to any changed nomenclature.

GUI Examples

Steve's Selection Toolbar mockup

Steve's Selection Toolbar mockup.png

using "Time Snap" Selection Toolbar

Ts.png

Previous Feature Requests relating to this proposal

None