Audacity  3.0.3
TrackPanelAx.h
Go to the documentation of this file.
1 /**********************************************************************
2 
3  Audacity: A Digital Audio Editor
4 
5  TrackPanelAx.h
6 
7  Leland Lucius
8 
9 **********************************************************************/
10 
11 #ifndef __AUDACITY_TRACK_PANEL_ACCESSIBILITY__
12 #define __AUDACITY_TRACK_PANEL_ACCESSIBILITY__
13 
14 
15 
16 #include <functional>
17 #include <memory>
18 
19 #include <wx/event.h> // to declare custom event types
20 #include <wx/setup.h> // for wxUSE_* macros
21 
22 #include <wx/string.h> // member variable
23 
24 #if wxUSE_ACCESSIBILITY
25 #include "widgets/WindowAccessible.h" // to inherit
26 #endif
27 
28 #include "ClientData.h" // to inherit
29 
30 class wxRect;
31 
32 class AudacityProject;
33 class Track;
34 class TrackList;
35 
36 // An event sent to the project
37 wxDECLARE_EXPORTED_EVENT(AUDACITY_DLL_API,
38  EVT_TRACK_FOCUS_CHANGE, wxCommandEvent);
39 
40 class TrackPanelAx final
41 #if wxUSE_ACCESSIBILITY
42  : public WindowAccessible
43 #endif
44 {
45 public:
46  TrackPanelAx(AudacityProject &project);
47  virtual ~ TrackPanelAx();
48 
49  using RectangleFinder = std::function< wxRect( Track& ) >;
50  void SetFinder( const RectangleFinder &finder ) { mFinder = finder; }
51 
52  // Returns currently focused track or first one if none focused
53  std::shared_ptr<Track> GetFocus();
54 
55  // Changes focus to a specified track
56  // Return is the actual focused track, which may be different from
57  // the argument when that is null
58  std::shared_ptr<Track> SetFocus( std::shared_ptr<Track> track = {} );
59 
60  // Returns TRUE if passed track has the focus
61  bool IsFocused( const Track *track );
62 
63  // Called to signal changes to a track
64  void Updated();
65 
66  void MessageForScreenReader(const TranslatableString& message);
67 
68 #if wxUSE_ACCESSIBILITY
69  // Retrieves the address of an IDispatch interface for the specified child.
70  // All objects must support this property.
71  wxAccStatus GetChild(int childId, wxAccessible** child) override;
72 
73  // Gets the number of children.
74  wxAccStatus GetChildCount(int* childCount) override;
75 
76  // Gets the default action for this object (0) or > 0 (the action for a child).
77  // Return wxACC_OK even if there is no action. actionName is the action, or the empty
78  // string if there is no action.
79  // The retrieved string describes the action that is performed on an object,
80  // not what the object does as a result. For example, a toolbar button that prints
81  // a document has a default action of "Press" rather than "Prints the current document."
82  wxAccStatus GetDefaultAction(int childId, wxString *actionName) override;
83 
84  // Returns the description for this object or a child.
85  wxAccStatus GetDescription(int childId, wxString *description) override;
86 
87  // Gets the window with the keyboard focus.
88  // If childId is 0 and child is NULL, no object in
89  // this subhierarchy has the focus.
90  // If this object has the focus, child should be 'this'.
91  wxAccStatus GetFocus(int *childId, wxAccessible **child) override;
92 
93  // Returns help text for this object or a child, similar to tooltip text.
94  wxAccStatus GetHelpText(int childId, wxString *helpText) override;
95 
96  // Returns the keyboard shortcut for this object or child.
97  // Return e.g. ALT+K
98  wxAccStatus GetKeyboardShortcut(int childId, wxString *shortcut) override;
99 
100  // Returns the rectangle for this object (id = 0) or a child element (id > 0).
101  // rect is in screen coordinates.
102  wxAccStatus GetLocation(wxRect& rect, int elementId) override;
103 
104  // Gets the name of the specified object.
105  wxAccStatus GetName(int childId, wxString *name) override;
106 
107  // Returns a role constant.
108  wxAccStatus GetRole(int childId, wxAccRole *role) override;
109 
110  // Gets a variant representing the selected children
111  // of this object.
112  // Acceptable values:
113  // - a null variant (IsNull() returns TRUE)
114  // - a list variant (GetType() == wxT("list"))
115  // - an integer representing the selected child element,
116  // or 0 if this object is selected (GetType() == wxT("long"))
117  // - a "void*" pointer to a wxAccessible child object
118  wxAccStatus GetSelections(wxVariant *selections) override;
119 
120  // Returns a state constant.
121  wxAccStatus GetState(int childId, long* state) override;
122 
123  // Returns a localized string representing the value for the object
124  // or child.
125  wxAccStatus GetValue(int childId, wxString* strValue) override;
126 
127  // Navigates from fromId to toId/toObject
128  wxAccStatus Navigate(wxNavDir navDir, int fromId, int* toId, wxAccessible** toObject) override;
129 
130  // Modify focus or selection
131  wxAccStatus Select(int childId, wxAccSelectionFlags selectFlags) override;
132 #else
133  wxWindow *GetWindow() const { return mWindow; }
134  void SetWindow( wxWindow *window ) { mWindow = window; }
135 #endif
136 
137 private:
138 
139  TrackList &GetTracks();
140  int TrackNum( const std::shared_ptr<Track> &track );
141  std::shared_ptr<Track> FindTrack( int num );
142 
144 
145 #if !wxUSE_ACCESSIBILITY
146  wxWindow *mWindow{};
147 #endif
148 
150 
151  std::weak_ptr<Track> mFocusedTrack;
153 
154  wxString mMessage;
157 };
158 
159 class AUDACITY_DLL_API TrackFocus final
160  : public ClientData::Base
161 {
162 public:
163  static TrackFocus &Get( AudacityProject &project );
164  static const TrackFocus &Get( const AudacityProject &project );
165 
166  explicit TrackFocus( AudacityProject &project );
167  ~TrackFocus() override;
168 
169  TrackFocus( const TrackFocus & ) PROHIBITED;
170  TrackFocus& operator=( const TrackFocus & ) PROHIBITED;
171 
172  // Report the currently focused track, which may be null, otherwise is
173  // a leader track
174  // This function is not const, because it may have a side effect of setting
175  // a focus if none was already set
176  Track *Get();
177 
178  // Set the track focus to a given track or to null
179  void Set( Track *pTrack );
180 
181  // Not equivalent to pTrack == this->Get(): may return true also for
182  // other channels than the leader
183  // As with Get(), this is not const
184  bool IsFocused( const Track *pTrack );
185 
186  void SetAccessible( wxWindow &owner,
187  std::unique_ptr< TrackPanelAx > pAccessible );
188 
189  void MessageForScreenReader(const TranslatableString& message);
190 
191  void UpdateAccessibility();
192 
193 private:
194 
196 
197 #if wxUSE_ACCESSIBILITY
198  TrackPanelAx *mAx{};
199 #else
200  std::unique_ptr<TrackPanelAx> mAx;
201 #endif
202 };
203 
204 #endif // __AUDACITY_TRACK_PANEL_ACCESSIBILITY__
TrackPanelAx::TrackPanelAx
TrackPanelAx(AudacityProject &project)
Definition: TrackPanelAx.cpp:39
TranslatableString
Holds a msgid for the translation catalog; may also bind format arguments.
Definition: TranslatableString.h:32
TrackPanelAx::mMessage
wxString mMessage
Definition: TrackPanelAx.h:154
TrackPanelAx::SetWindow
void SetWindow(wxWindow *window)
Definition: TrackPanelAx.h:134
TrackPanelAx::mMessageCount
int mMessageCount
Definition: TrackPanelAx.h:156
TrackPanelAx::mFocusedTrack
std::weak_ptr< Track > mFocusedTrack
Definition: TrackPanelAx.h:151
TrackPanelAx::SetFocus
std::shared_ptr< Track > SetFocus(std::shared_ptr< Track > track={})
Definition: TrackPanelAx.cpp:95
TrackFocus
Definition: TrackPanelAx.h:161
TrackPanelAx::Updated
void Updated()
Definition: TrackPanelAx.cpp:202
TrackList
A flat linked list of tracks supporting Add, Remove, Clear, and Contains, serialization of the list o...
Definition: Track.h:1264
TrackPanelAx::GetTracks
TrackList & GetTracks()
Definition: TrackPanelAx.cpp:56
TrackPanelAx::MessageForScreenReader
void MessageForScreenReader(const TranslatableString &message)
Definition: TrackPanelAx.cpp:222
ClientData::Base
A convenient default parameter for class template Site.
Definition: ClientData.h:28
TrackPanelAx
Helper to TrackPanel to give accessibility.
Definition: TrackPanelAx.h:44
ClientData.h
Utility ClientData::Site to register hooks into a host class that attach client data.
TrackPanelAx::GetWindow
wxWindow * GetWindow() const
Definition: TrackPanelAx.h:133
TrackPanelAx::~ TrackPanelAx
virtual ~ TrackPanelAx()
TrackPanelAx::mTrackName
bool mTrackName
Definition: TrackPanelAx.h:155
BasicUI::Get
Services * Get()
Fetch the global instance, or nullptr if none is yet installed.
Definition: BasicUI.cpp:26
name
const TranslatableString name
Definition: Distortion.cpp:98
TrackFocus::mProject
AudacityProject & mProject
Definition: TrackPanelAx.h:195
WindowAccessible
An alternative to using wxWindowAccessible, which in wxWidgets 3.1.1 contained GetParent() which was ...
TrackPanelAx::GetFocus
std::shared_ptr< Track > GetFocus()
Definition: TrackPanelAx.cpp:65
TrackPanelAx::mProject
AudacityProject & mProject
Definition: TrackPanelAx.h:143
TrackPanelAx::mFinder
RectangleFinder mFinder
Definition: TrackPanelAx.h:149
TrackPanelAx::RectangleFinder
std::function< wxRect(Track &) > RectangleFinder
Definition: TrackPanelAx.h:49
TrackPanelAx::IsFocused
bool IsFocused(const Track *track)
Definition: TrackPanelAx.cpp:153
TrackFocus::TrackFocus
TrackFocus(const TrackFocus &) PROHIBITED
WindowAccessible.h
Track
Abstract base class for an object holding data associated with points on a time axis.
Definition: Track.h:239
TrackPanelAx::FindTrack
std::shared_ptr< Track > FindTrack(int num)
Definition: TrackPanelAx.cpp:188
TrackPanelAx::SetFinder
void SetFinder(const RectangleFinder &finder)
Definition: TrackPanelAx.h:50
AudacityProject
The top-level handle to an Audacity project. It serves as a source of events that other objects can b...
Definition: Project.h:113
TrackPanelAx::mNumFocusedTrack
int mNumFocusedTrack
Definition: TrackPanelAx.h:152
wxDECLARE_EXPORTED_EVENT
wxDECLARE_EXPORTED_EVENT(AUDACITY_DLL_API, EVT_TRACK_FOCUS_CHANGE, wxCommandEvent)
TrackFocus::mAx
std::unique_ptr< TrackPanelAx > mAx
Definition: TrackPanelAx.h:200
TrackPanelAx::mWindow
wxWindow * mWindow
Definition: TrackPanelAx.h:146
TrackFocus::operator=
TrackFocus & operator=(const TrackFocus &) PROHIBITED
TrackPanelAx::TrackNum
int TrackNum(const std::shared_ptr< Track > &track)
Definition: TrackPanelAx.cpp:170