1////////////////////////////////////////////////////////////////////////////////
2//
3//  ADOBE SYSTEMS INCORPORATED
4//  Copyright 2009 Adobe Systems Incorporated
5//  All Rights Reserved.
6//
7//  NOTICE: Adobe permits you to use, modify, and distribute this file
8//  in accordance with the terms of the license agreement accompanying it.
9//
10////////////////////////////////////////////////////////////////////////////////
11
12package spark.accessibility
13{
14
15import flash.accessibility.Accessibility;
16import flash.events.Event;
17import flash.events.FocusEvent;
18
19import mx.accessibility.AccImpl;
20import mx.accessibility.AccConst;
21import mx.core.UIComponent;
22import mx.core.mx_internal;
23import spark.components.RichEditableText;
24
25use namespace mx_internal;
26
27/**
28 *  RichEditableTextAccImpl is the accessibility implementation class
29 *  for spark.components.RichEditableText.
30 *
31 *  <p>When a Spark RichEditableText is created,
32 *  its <code>accessibilityImplementation</code> property
33 *  is set to an instance of this class.
34 *  The Flash Player then uses this class to allow MSAA clients
35 *  such as screen readers to see and manipulate the RichEditableText.
36 *  See the mx.accessibility.AccImpl and
37 *  flash.accessibility.AccessibilityImplementation classes
38 *  for background information about accessibility implementation
39 *  classes and MSAA.</p>
40 *
41 *  <p><b>Children</b></p>
42 *
43 *  <p>A RichEditableText has no MSAA children.</p>
44 *
45 *  <p><b>Role</b></p>
46 *
47 *  <p>The MSAA Role of a RichEditableText is ROLE_SYSTEM_TEXT.</p>
48 *
49 *  <p><b>Name</b></p>
50 *
51 *  <p>The MSAA Name of a RichEditableText is, by default, the empty string.
52 *  When wrapped in a FormItem element, the Name is the FormItem's label.
53 *  To override this behavior,
54 *  set the RichEditableText's <code>accessibilityName</code> property.</p>
55 *
56 *  <p>When the Name changes,
57 *  a RichEditableText dispatches the MSAA event EVENT_OBJECT_NAMECHANGE.</p>
58 *
59 *  <p><b>Description</b></p>
60 *
61 *  <p>The MSAA Description of a RichEditableText is, by default,
62 *  the empty string, but you can set the RichEditableText's
63 *  <code>accessibilityDescription</code> property.</p>
64 *
65 *  <p><b>State</b></p>
66 *
67 *  <p>The MSAA State of a RichEditableText is a combination of:
68 *  <ul>
69 *    <li>STATE_SYSTEM_UNAVAILABLE (when enabled is false)</li>
70 *    <li>STATE_SYSTEM_FOCUSABLE (when enabled is true)</li>
71 *    <li>STATE_SYSTEM_FOCUSED
72 *    (when enabled is true and the RichEditableText has focus)</li>
73 *    <li>STATE_SYSTEM_PROTECTED (when displayAsPassword is true)</li>
74 *    <li>STATE_SYSTEM_READONLY (when editable is false)</li>
75 *  </ul></p>
76 *
77 *  <p>When the State changes,
78 *  a RichEditableText dispatches the MSAA event EVENT_OBJECT_STATECHANGE.</p>
79 *
80 *  <p><b>Value</b></p>
81 *
82 *  <p>The MSAA Value of a RichEditableText is equal to
83 *  its <code>text</code> property.</p>
84 *
85 *  <p>When the Value changes,
86 *  a RichEditableText dispatches the MSAA event EVENT_OBJECT_VALUECHANGE.</p>
87 *
88 *  <p><b>Location</b></p>
89 *
90 *  <p>The MSAA Location of a RichEditableText is its bounding rectangle.</p>
91 *
92 *  <p><b>Default Action</b></p>
93 *
94 *  <p>A RichEditableText does not have an MSAA DefaultAction.</p>
95 *
96 *  <p><b>Focus</b></p>
97 *
98 *  <p>A RichEditableText accepts focus.
99 *  When it does so it dispatches the MSAA event EVENT_OBJECT_FOCUS.</p>
100 *
101 *  <p><b>Selection</b></p>
102 *
103 *  <p>A RichEditableText does not support selection in the MSAA sense,
104 *  and text selection is not part of Microsoft's IAccessibility COM interface.
105 *  But, in Player 10.1 and later, screen readers can determine
106 *  the currently selected text range via the <code>GetSelection()</code> method
107 *  in Adobe's ISimpleTextSelection COM interface, which calls the
108 *  <code>selectionAnchorIndex</code> and <code>selectionActiveIndex</code>
109 *  getters in this class.</p>
110 *
111 *  @langversion 3.0
112 *  @playerversion Flash 10
113 *  @playerversion AIR 1.5
114 *  @productversion Flex 4
115 */
116public class RichEditableTextAccImpl extends AccImpl
117{
118    include "../core/Version.as";
119
120    //--------------------------------------------------------------------------
121    //
122    //  Class methods
123    //
124    //--------------------------------------------------------------------------
125
126    /**
127     *  Enables accessibility in the RichEditableText class.
128     *
129     *  <p>This method is called by application startup code
130     *  that is autogenerated by the MXML compiler.
131     *  Afterwards, when instances of RichEditableText are initialized,
132     *  their <code>accessibilityImplementation</code> property
133     *  will be set to an instance of this class.</p>
134     *
135     *  @langversion 3.0
136     *  @playerversion Flash 10
137     *  @playerversion AIR 1.5
138     *  @productversion Flex 4
139     */
140    public static function enableAccessibility():void
141    {
142        RichEditableText.createAccessibilityImplementation =
143            createAccessibilityImplementation;
144    }
145
146    /**
147     *  @private
148     *  Creates a RichEditableText's AccessibilityImplementation object.
149     *  This method is called from UIComponent's
150     *  initializeAccessibility() method.
151     */
152    mx_internal static function createAccessibilityImplementation(
153        component:UIComponent):void
154    {
155        component.accessibilityImplementation =
156            new RichEditableTextAccImpl(component);
157    }
158
159    //--------------------------------------------------------------------------
160    //
161    //  Constructor
162    //
163    //--------------------------------------------------------------------------
164
165    /**
166     *  Constructor.
167     *
168     *  @param master The UIComponent instance that this AccImpl instance
169     *  is making accessible.
170     *
171     *  @langversion 3.0
172     *  @playerversion Flash 10
173     *  @playerversion AIR 1.5
174     *  @productversion Flex 4
175     */
176    public function RichEditableTextAccImpl(master:UIComponent)
177    {
178        super(master);
179
180        role = AccConst.ROLE_SYSTEM_TEXT;
181    }
182
183    //--------------------------------------------------------------------------
184    //
185    //  Overridden properties: AccImpl
186    //
187    //--------------------------------------------------------------------------
188
189    //----------------------------------
190    //  eventsToHandle
191    //----------------------------------
192
193    /**
194     *  @private
195     *  Array of events that we should listen for from the master component.
196     */
197    override protected function get eventsToHandle():Array
198    {
199        return super.eventsToHandle.concat([ Event.CHANGE ]);
200    }
201
202    //--------------------------------------------------------------------------
203    //
204    //  Properties: ISimpleTextSelection
205    //
206    //--------------------------------------------------------------------------
207
208    //----------------------------------
209    //  selectionActiveIndex
210    //----------------------------------
211
212    /**
213     *  A character position, relative to the beginning of the
214     *  <code>text</code> String of the RichEditableText,
215	 *  specifying the end of the selection
216     *  that moves when the selection is extended with the arrow keys.
217     *
218     *  <p>The active position may be either the start
219     *  or the end of the selection.</p>
220     *
221     *  <p>For example, if you drag-select from position 12 to position 8,
222     *  then <code>selectionAnchorPosition</code> will be 12
223     *  and <code>selectionActivePosition</code> will be 8,
224     *  and when you press Left-Arrow <code>selectionActivePosition</code>
225     *  will become 7.</p>
226     *
227     *  <p>A value of -1 indicates "not set".</p>
228	 *
229	 *  <p>In Player 10.1 and later, and AIR 2.0 and later,
230	 *  an AccessibilityImplementation can implement
231	 *  <code>selectionAnchorIndex</code> and <code>selectionAnchorIndex</code>
232	 *  in order to make an accessibility client aware of the text selection
233	 *  in TLF text via Adobe's ISimpleTextSelection COM interface.</p>
234     *
235     *  @default -1
236     *
237	 *  @see spark.accessibility.RichEditableTextAccImpl#selectionAnchorIndex
238     *  @see spark.components.RichEditableText#selectionActivePosition
239     *
240     *  @langversion 3.0
241     *  @playerversion Flash 10.1
242     *  @playerversion AIR 2.0
243     *  @productversion Flex 4
244     */
245	public function get selectionActiveIndex():int
246	{
247		return RichEditableText(master).selectionActivePosition;
248	}
249
250    //----------------------------------
251    //  selectionAnchorIndex
252    //----------------------------------
253
254    /**
255     *  A character position, relative to the beginning of the
256     *  <code>text</code> String of the RichEditableText,
257	 *  specifying the end of the selection
258     *  that stays fixed when the selection is extended with the arrow keys.
259     *
260     *  <p>The anchor position may be either the start
261     *  or the end of the selection.</p>
262     *
263     *  <p>For example, if you drag-select from position 12 to position 8,
264     *  then <code>selectionAnchorPosition</code> will be 12
265     *  and <code>selectionActivePosition</code> will be 8,
266     *  and when you press Left-Arrow <code>selectionActivePosition</code>
267     *  will become 7.</p>
268     *
269     *  <p>A value of -1 indicates "not set".</p>
270	 *
271	 *  <p>In Player 10.1 and later, and AIR 2.0 and later,
272	 *  an AccessibilityImplementation can implement
273	 *  <code>selectionAnchorIndex</code> and <code>selectionAnchorIndex</code>
274	 *  in order to make an accessibility client aware of the text selection
275	 *  in TLF text via Adobe's ISimpleTextSelection COM interface.</p>
276     *
277     *  @default -1
278     *
279	 *  @see spark.accessibility.RichEditableTextAccImpl#selectionActiveIndex
280     *  @see spark.components.RichEditableText#selectionAnchorPosition
281     *
282     *  @langversion 3.0
283     *  @playerversion Flash 10.1
284     *  @playerversion AIR 2.0
285     *  @productversion Flex 4
286     */
287	public function get selectionAnchorIndex():int
288	{
289		return RichEditableText(master).selectionAnchorPosition;
290	}
291
292    //--------------------------------------------------------------------------
293    //
294    //  Overridden methods: AccessibilityImplementation
295    //
296    //--------------------------------------------------------------------------
297
298    /**
299     *  @private
300     *  IAccessible method for returning the text value of the RichEditableText
301     *
302     *  @param childID uint
303     *
304     *  @return Value String
305     */
306    override public function get_accValue(childID:uint):String
307    {
308        return RichEditableText(master).text;
309    }
310
311    /**
312     *  @private
313     *  IAccessible method for returning the state of the RichEditableText.
314     *  States are predefined for all the components in MSAA.
315     *  Values are assigned to each state.
316     *
317     *  @param childID uint
318     *
319     *  @return State uint
320     */
321    override public function get_accState(childID:uint):uint
322    {
323        var accState:uint = getState(childID);
324        if (!RichEditableText(master).editable)
325            accState |= AccConst.STATE_SYSTEM_READONLY;
326        if (RichEditableText(master).displayAsPassword)
327            accState |= AccConst.STATE_SYSTEM_PROTECTED;
328        return accState;
329    }
330
331    //--------------------------------------------------------------------------
332    //
333    //  Overridden event handlers: AccImpl
334    //
335    //--------------------------------------------------------------------------
336
337    /**
338     *  @private
339     *  Override the generic event handler.
340     *  All AccImpl must implement this
341     *  to listen for events from its master component.
342     */
343    override protected function eventHandler(event:Event):void
344    {
345        // Let AccImpl class handle the events
346        // that all accessible UIComponents understand.
347        $eventHandler(event);
348
349        switch (event.type)
350        {
351            case Event.CHANGE:
352            {
353                Accessibility.sendEvent(
354					master, 0, AccConst.EVENT_OBJECT_VALUECHANGE, true);
355                break;
356            }
357        }
358    }
359
360    /**
361     *  @private
362     *  method for returning the name of the RichEditableText
363     *  should return the value
364     *
365     *  @param childID uint
366     *
367     *  @return Name String
368     */
369    override protected function getName(childID:uint):String
370    {
371        return "";
372    }
373
374}
375
376}
377