View source for Withdrawn: Proposal Rename "Snap To"

{{Proposal_Header|This page is a proposal to rename the "Snap To" function |}}
__NOTOC__

{{ednote|'''Peter 12Nov13:''' I strongly recommend that we withdraw this proposal
*Now that we have the new selectable time snapping it seems to me that "Snap To" is a perfectly acceptable choice.  
*To my mind it works better as "Snap To Nearest" and "Snap To Previous" work better than any of the proposed alternatives, especially now that there is a snap box that says off/next/previous aligned with the time format boxes.  
*Plus we have made the distinction pretty clear by altering the nomenclature of the other snappers to "Boundary Snap Guides"
<p>'''Gale 12Nov13:''' I suggest you make a new Category "Proposals Completed or Withdrawn" and move this, [[Proposal Normalize]] and any others into that. </p>
*'''Peter 13Nov13:''' created new category as per Gale's suggestion and moved this page into that category and renamed it as "Withdrawn: Proposal ..."
}}

==The Problem==
We have two different "Snap To " functions in Audacity
#Time format snapping - currently identified as '''"Snap To"''' in Audacity
#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"''' or '''Format Snap'''.  

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

===Alternative nomenclature suggestions===
*Steve suggested "Selection Snap" ''(and moving the snap to the right end of the Selection Toolbar)''.
**Gale: -1

*Gale further suggested '''"Format Snap"'''

==Developer/QA Backing==
*Gale: +1 for "Time Snap"
**'''Gale 30Apr13 (via email):''' I think a rename to "Time Snap" or "Format Snap" would further discourage mistaken enabling of "Snap To". We are snapping to the "Selection Format" (as we call it in the Manual) but samples and frames are not "time formats" in the sense that seconds or milliseconds are. Time Snap could imply this is Timeline/Label Track snapping but not audio track snapping (to knowledgeable folk who realise the audio track is based on samples, not time).
*Peter: +1 for "Time Snap" or "Format 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
:[[File:Steve's Selection Toolbar mockup.png]]
using "Time Snap" Selection Toolbar 
:[[File:Ts.png]]

==Previous Feature Requests relating to this proposal==
None


[[Category:Proposals Completed or Withdrawn]]