AccessibilityImplementation  - AS3

Wskazuje kod błędu. Błędy są sygnalizowane za pośrednictwem odrębnej właściwości, a nie w wartościach zwracanych. Aby zasygnalizować błąd, należy przypisać właściwości errno jeden z kodów błędów udokumentowanych w dodatku z opisem stałych klasy AccessibilityImplementation. Spowoduje to zignorowanie wartości zwróconej. Właściwość errno obiektu AccessibilityImplementation w kodzie użytkownika jest zawsze czyszczona (ustawiana na zero) przez odtwarzacz przed wywołaniem którejkolwiek metody klasy AccessibilityImplementation.

Powiązane elementy interfejsu API

Służy do tworzenia szkieletu ułatwień dostępu dla składnika. Jeśli dany składnik ma być udostępniony użytkownikom bez jakiejkolwiek implementacji ułatwień dostępu w kodzie ActionScript, firma Adobe zaleca dodanie szkieletu ułatwień dostępu dla składnika. Szkielet taki powoduje, że w kontekście ułatwień dostępu program Flash Player traktuje składnik jak prostą grafikę, nie ujawniając wewnętrznej struktury przycisków, pól tekstowych i innych elementów zawartych w składniku.

Aby utworzyć szkielet ułatwień dostępu dla składnika, należy utworzyć podklasę odpowiedniej klasy AccImpl, przesłaniając właściwość szkieletową wartością true.

Powiązane elementy interfejsu API

Konstruktor statyczny. Nie należy bezpośrednio tworzyć wystąpień klasy AccessibilityImplementation przez wywołanie jej konstruktora. Nowe implementacje ułatwień dostępu należy tworzyć, rozszerzając klasę mx.accessibility.AccImpl na potrzeby każdego nowego składnika.

Powiązane elementy interfejsu API

Metoda IAccessible wykonująca domyślą czynność skojarzoną ze składnikiem reprezentowanym przez tę klasę AccessibilityImplementation lub jeden z jego elementów podrzędnych.

Tę metodę należy zaimplementować tylko w sytuacji, gdy klasa AccessibilityImplementation reprezentuje element interfejsu użytkownika, z którym w modelu MSAA skojarzona jest domyślna czynność.

Jeśli metoda accDoDefaultAction() jest implementowana tylko na potrzeby klasy AccessibilityImplementation lub jej elementów podrzędnych, w niektórych przypadkach konieczne będzie wskazanie, że dla przekazanego identyfikatora childID nie ma czynności domyślnej. W tym celu należy przypisać właściwości errno wartość E_MEMBERNOTFOUND.

Parametry

     override public function accDoDefaultAction(childID:uint):void
     {
         if (childID > 0)
             ListBase(master).selectedIndex = childID - 1;
     }

Metoda MSAA zwracająca obiekt DisplayObject lub Rectangle określający obwiednię elementu podrzędnego w klasie AccessibilityImplementation.

Ta metoda nigdy nie jest wywoływana z parametrem childID równym zero. Jeśli obiekt klasy AccessibilityImplementation nigdy nie będzie zawierał elementów podrzędnych, nie należy implementować tej metody. Jeśli obiekt klasy AccessibilityImplementation może zawierać elementy podrzędne, ta metoda jest wymagana.

Zwykle wystarczającą funkcjonalnością metody jest zwrócenie obiektu reprezentującego sam element podrzędny. Takie rozwiązanie jest poprawne, o ile tylko element podrzędny należy do klasy DisplayObject. W takich przypadkach wystarczy zwrócić obiekt DisplayObject odpowiadający nazwie instancji skojarzonej z odpowiednim obiektem na liście wyświetlania.

Jeśli element podrzędny nie spełnia warunku opisanego powyżej, można samodzielnie obliczyć obwiednię i zwrócić obiekt Rectangle z wypełnionymi właściwościami x, y, width i height. Właściwości x i y wskazują lewy górny róg obwiedni, a właściwości width i height określają jej wymiary. Wszystkie cztery wartości powinny być wyrażone w pikselach stołu montażowego i liczone względem punktu początkowego składnika reprezentowanego przez obiekt AccessibilityImplementation. Właściwości x i y mogą mieć wartości ujemne, ponieważ punkt początkowy obiektu DisplayObject nie zawsze znajduje się w jego lewym górnym rogu.

Jeśli element podrzędny określony przez parametr childID nie jest widoczny (tzn. metoda get_accState zwróciłaby wartość zawierającą stałą STATE_SYSTEM_INVISIBLE), metoda accLocation może zwrócić wartość null. Metoda może także zwrócić obiekt Rectangle odzwierciedlający współrzędne, w których znajdowałby się element podrzędny, gdyby był widoczny.

Parametry

Więcej informacji

Powiązane elementy interfejsu API

     override public function accLocation(childID:uint):*
     
     {
         var listBase:ListBase = ListBase(master);
     
         var index:uint = childID - 1;
         
         if (index < listBase.verticalScrollPosition ||
             index >= listBase.verticalScrollPosition + listBase.rowCount)
         {
             return null;
         }
         var item:Object = getItemAt(index);
     
         return listBase.itemToItemRenderer(item);
     }
     

Metoda IAccessible służąca do zmiany zaznaczenia w składniku reprezentowanym przez ten obiekt AccessibilityImplementation.

Parametr childID zawsze będzie miał wartość różną od zera. Ta metoda zawsze stosowana jest do jednego elementu podrzędnego, a nie całego składnika; zaznaczeniem całego składnika zarządza program Flash Player.

Parametr selFlag jest polem bitowym zawierającym jedną lub większą liczbę stałych flag zaznaczenia, które umożliwiają klientowi MSAA określenie, w jaki sposób element o identyfikatorze childID powinien być zaznaczany lub przejmować aktywność. Poniżej zamieszczono opisy stałych flag zaznaczenia i ich znaczenie dla implementacji ułatwień dostępu. Ze względów praktycznych większość implementacji tej metody w implementacjach ułatwień dostępu dziedziczących z klasy Flex mx.accessibility.ListBaseAccImpl ignoruje stałą selFlag i obsługuje zaznaczanie wielu elementów przy wykorzystaniu mechanizmów interakcji składnika z klawiaturą.

Parametr selFlag może, ale nie musi zawierać flagę SELFLAG_TAKEFOCUS. Jeśli zawiera, należy uaktywnić wskazany element podrzędny childID oraz traktować go jako zakotwiczenie zaznaczenia, chyba że parametr zawiera także flagę SELFLAG_EXTENDSELECTION. W przeciwnym razie nie należy zmieniać stanu aktywności elementu podrzędnego ani zakotwiczenia zaznaczenia, mimo że opisane poniżej dodatkowe flagi mogą modyfikować zaznaczenie.

Argument selFlag będzie zawsze zawierał jedną z czterech następujących flag, które określają żądany rodzaj modyfikacji zaznaczenia:

• SELFLAG_TAKESELECTION: Anuluj ewentualne istniejące zaznaczenie i zaznacz określony element childID.

• SELFLAG_EXTENDSELECTION: Oblicz zakres elementów podrzędnych między zakotwiczeniem zaznaczenia a określonym elementem childID włącznie. Jeśli obecna jest flaga SELFLAG_ADDSELECTION, dodaj do zaznaczenia wszystkie elementy z zakresu. Jeśli obecna jest flaga SELFLAG_REMOVESELECTION, usuń z zaznaczenia wszystkie elementy z zakresu. Jeśli nie jest obecna ani flaga SELFLAG_ADDSELECTION, ani SELFLAG_REMOVESELECTION, wszystkie elementy z zakresu powinny przejąć stan zaznaczenia, w jakim jest element będący zakotwiczeniem — jeśli zakotwiczenie jest zaznaczone, należy je dodać do zaznaczenia; w przeciwnym razie należy je usunąć z zaznaczenia.

• SELFLAG_ADDSELECTION (bez flagi SELFLAG_EXTENDSELECTION): Dodaj określony element childID do zaznaczenia.

• SELFLAG_REMOVESELECTION (bez flagi SELFLAG_EXTENDSELECTION): Usuń określony element childID z zaznaczenia.

Należy zwrócić uwagę, że w przypadku składników, które nie umożliwiają zaznaczenia więcej niż jednego elementu, jedynymi dozwolonymi wartościami parametru selFlag są SELFLAG_TAKEFOCUS i SELFLAG_TAKESELECTION. Teoretycznie w składnikach niedopuszczających zaznaczenia wielu elementów można byłoby również obsługiwać flagę SELFLAG_REMOVESELECTION, aby umożliwić użytkownikowi wymuszenie braku zaznaczenia (null), ale w praktyce większość takich składników nie obsługuje tej flagi, a klienty MSAA mogą nie podejmować prób wykonania takiej operacji.

Jeśli przekazana kombinacja flag jest niepoprawna, należy przypisać właściwości errno wartość E_INVALIDARG.

Należy również zauważyć, że w momencie wywołania accSelect okno aplikacji zawierającej program Flash Player staje się aktywne (tzw. aktywność hosta); podobnie, aktywny staje się dany składnik w programie Flash Player.

Parametry

Więcej informacji

Powiązane elementy interfejsu API

override public function accSelect(selFlag:uint, childID:uint):void
     {
         
         var listBase:ListBase = ListBase(master);
         
         var index:uint = childID - 1;
         
         if (index >= 0 && index < listBase.dataProvider.length)
             listBase.selectedIndex = index;
     }
     

Metoda modelu MSAA służąca do zwracania domyślnej czynności składnika reprezentowanego przez ten obiekt AccessibilityImplementation lub jednego z jego elementów potomnych.

Metodę tę należy implementować tylko w sytuacji, gdy obiekt AccessibilityImplementation reprezentuje element interfejsu użytkownika, który w modelu MSAA ma przypisaną czynność domyślną; metoda powinna zwracać dokładnie taki ciąg znaków, jaki jest określony w modelu MSAA. Na przykład ciągiem czynności domyślnej dla składnika Button jest ciąg "Press".

Jeśli metoda get_accDefaultAction jest implementowana tylko na potrzeby klasy AccessibilityImplementation lub jej elementów podrzędnych, w niektórych przypadkach konieczne będzie wskazanie, że dla przekazanego identyfikatora childID nie ma czynności domyślnej. W tym celu wystarczy zwrócić wartość null.

Parametry

Więcej informacji

Powiązane elementy interfejsu API

override public function get_accDefaultAction(childID:uint):String
     {
         if (childID == 0)
             return null;
     
         return "Double Click";
     }

Metoda MSAA służąca do zwracania identyfikatora (liczby całkowitej bez znaku) elementu podrzędnego, który jest aktywny w składniku, o ile istnieje aktywny element. Jeśli żaden element podrzędny nie jest aktywny, metoda zwraca zero.

Więcej informacji

Powiązane elementy interfejsu API

override public function get_accFocus():uint
     {
     var index:uint = ListBase(master).selectedIndex;
     
     return index >= 0 ? index + 1 : 0;
     }

Metoda modelu MSAA służąca do zwracania nazwy składnika reprezentowanego przez ten obiekt AccessibilityImplementation lub jednego z jego elementów podrzędnych.

W przypadku samego obiektu AccessibilityImplementation (childID == 0), jeśli metoda nie jest zaimplementowana lub nie zwraca wartości, program Flash Player używa wartości właściwości AccessibilityProperties.name, o ile jest obecna.

W przypadku obiektów AccessibilityImplementation, które mogą mieć elementy podrzędne, implementacja tej metody jest wymagana i musi zwracać ciąg znaków, gdy parametr childID jest różny od zera.

W zależności od typu elementu interfejsu użytkownika nazwy w modelu MSAA mają różne znaczenie: są albo nazwami przypisanymi przez autora, albo odzwierciedlają faktyczną treść tekstową elementu. Zwykle obiekt AccessibilityImplementation należy do tej pierwszej kategorii. Jego właściwość name jest nazwą przypisaną przez autora. Elementy podrzędne zawsze należą do drugiej kategorii. Ich nazwy odzwierciedlają ich treść tekstową.

Gdy właściwość name obiektu AccessibilityImplementation jest nazwą przypisaną przez autora, istnieją dwa sposoby określania nazwy składnika. Po pierwsze, nazwa może być obecna w samym składniku; na przykład składnik pola wyboru może zawierać etykietę tekstową pełniącą rolę jego nazwy. Drugi sposób — używany, gdy nie można skorzystać z pierwszego — polega na poszukiwaniu nazw określonych w interfejsie użytkownika, kolejno aż do osiągnięcia nazwy AccessibilityProperties.name. Ten sposób „rezerwowy” umożliwia określanie nazw tak samo, jak dla pozostałych obiektów Sprite lub MovieClip.

A zatem nazwa samego obiektu AccessibilityImplementation (childID == zero) może być przypisana na trzy sposoby:

• Nazwa przypisana przez autora wewnątrz składnika. Metoda get_accName powinna być zaimplementowana i gdy parametr childID jest równy zero, powinna zwracać ciąg znaków zawierający nazwę obiektu AccessibilityImplementation. Jeśli parametr childID jest równy zero, ale obiekt AccessibilityImplementation nie ma nazwy, metoda get_accName powinna zwracać pusty ciąg znaków, aby zapobiec użyciu przez odtwarzacz nazwy zapisanej we właściwości AccessibilityProperties.name.

• Nazwa przypisana przez autora w interfejsie użytkownika. Jeśli obiekt AccessibilityImplementation może mieć elementy podrzędne, metoda get_accName powinna być zaimplementowana, ale nie powinna zwracać wartości, gdy parametr childID jest równy zero. Jeśli obiekt AccessibilityImplementation nigdy nie będzie miał elementów podrzędnych, nie należy implementować metody get_accName.

• Nazwa odzwierciedlająca treść. Metoda get_accName powinna być zaimplementowana i powinna zwracać odpowiedni ciąg znaków, gdy parametr childID ma wartość zero. Jeśli parametr childId jest równy zero, ale obiekt AccessibilityImplementation nie ma zawartości, metoda get_accName powinna zwracać pusty ciąg znaków, aby zapobiec użyciu przez odtwarzacz nazwy zapisanej we właściwości AccessibilityProperties.name.

Należy zwrócić uwagę, że do elementów podrzędnych (jeśli obiekt AccessibilityImplementation może je mieć) zawsze ma zastosowanie trzeci przypadek. Metoda get_accName powinna być zaimplementowana i powinna zwracać odpowiedni ciąg znaków, gdy parametr childID ma wartość różną od zera.

Parametry

Więcej informacji

Powiązane elementy interfejsu API

override public function get_accName(childID:uint):String
     {
         // Start with the name of the component's parent form 
          // if the component is contained within a form
         var accName:String = UIComponentAccImpl.getFormName(master);
     
         // If the element requested is the component itself, 
         // append the value of any assigned accessibilityProperties.name    
         if (childID == 0 && master.accessibilityProperties 
             && master.accessibilityProperties.name 
                 && master.accessibilityProperties.name != "")
             accName += master.accessibilityProperties.name + " ";
     
         // Append the value of the childIDs name 
     // returned by the component-specific override 
     // of the mx.accessibility.AccImpl.getName() utility function,
         // and append the component's status returned by the 
     // component-specific override of the 
     // mx.accessibility.AccImpl.getStatusName() utility function
         accName += getName(childID) + getStatusName();
     
     // Return the assembled String if it is neither empty nor null, 
     // otherwise return null
         return (accName != null && accName != "") ? accName : null;
     }

Metoda modelu MSAA służąca do zwracania roli systemowej składnika reprezentowanego przez ten obiekt AccessibilityImplementation lub jednego z jego elementów podrzędnych. Wszystkie składniki w modelu MSAA mają predefiniowane role systemowe.

Parametry

Więcej informacji

Powiązane elementy interfejsu API

Metoda modelu MSAA służąca do zwracania tablicy zawierającej identyfikatory wszystkich elementów podrzędnych, które są zaznaczone. Zwrócona tablica może zawierać zero, jeden lub większą liczbę identyfikatorów. Wszystkie identyfikatory są liczbami całkowitymi bez znaku.

Więcej informacji

Powiązane elementy interfejsu API

     override public function get_accSelection():Array
     {
         var accSelection:Array = [];
     
         var selectedIndices:Array = ListBase(master).selectedIndices;
         
         var n:int = selectedIndices.length;
         for (var i:int = 0; i < n; i++)
         {
             accSelection[i] = selectedIndices[i] + 1;
         }
         
         return accSelection;
     }
     

Metoda interfejsu IAccessible służąca do zwracania bieżącego stanu (w środowisku wykonawczym) składnika reprezentowanego przez ten obiekt AccessibilityImplementation lub jednego z jego elementów podrzędnych.

Te metoda musi zwracać kombinację złożoną z zera, jednej lub większej liczby stałych oznaczających stany obiektów predefiniowanych dla składników w modelu MSAA. Gdy składnik ma więcej niż jeden stan, stałe powinny być zsumowane bitowo w jedno pole bitowe za pomocą operatora |, czyli bitowego operatora OR.

Aby wskazać, że składnik nie znajduje się w żadnym ze stanów określonych przez stałe, metoda powinna zwrócić zero.

Nie ma potrzeby śledzenia ani zgłaszania stanów STATE_SYSTEM_FOCUSABLE i STATE_SYSTEM_FOCUSED. Program Flash Player obsługuje te stany automatycznie.

Parametry

Więcej informacji

Powiązane elementy interfejsu API

     override public function get_accState(childID:uint):uint
     {
         var accState:uint = getState(childID);
     
         if (childID > 0) 
         {
             var listBase:ListBase = ListBase(master);
     
             var index:uint = childID - 1;
     
             // For returning states (OffScreen and Invisible)
             // when the list Item is not in the displayed rows.
             if (index < listBase.verticalScrollPosition ||
                 index >= listBase.verticalScrollPosition + listBase.rowCount)
             {
                 accState |= (STATE_SYSTEM_OFFSCREEN |
                              STATE_SYSTEM_INVISIBLE);
             }
             else
             {
                 accState |= STATE_SYSTEM_SELECTABLE;
     
                 var item:Object = getItemAt(index);
     
                 var renderer:IListItemRenderer =
                     listBase.itemToItemRenderer(item);
     
                 if (renderer != null && listBase.isItemSelected(renderer.data))
                     accState |= STATE_SYSTEM_SELECTED | STATE_SYSTEM_FOCUSED;
             }
         }
     
         return accState;
     }

Metoda modelu MSAA służąca do zwracania wartości (w środowisku wykonawczym) składnika reprezentowanego przez ten obiekt AccessibilityImplementation lub jednego z jego elementów potomnych.

Tę metodę należy zaimplementować tylko w sytuacji, gdy klasa AccessibilityImplementation reprezentuje element interfejsu użytkownika, z którym w modelu MSAA skojarzona jest wartość. Należy pamiętać, że niektóre elementy interfejsu, które pozornie mają „wartość”, udostępniają ją za pośrednictwem innych metod, takich jak get_accName (np. tekst), get_accState (np. pola wyboru) lub get_accSelection (np. pola listy).

Jeśli metoda get_accValue jest implementowana tylko na potrzeby klasy AccessibilityImplementation lub jej elementów podrzędnych, w niektórych przypadkach konieczne będzie wskazanie, że w odniesieniu do przekazanego identyfikatora childID nie istnieje pojęcie „wartości”. W tym celu wystarczy zwrócić wartość null.

Parametry

Więcej informacji

Powiązane elementy interfejsu API

override public function get_accValue(childID:uint):String
     {
         var accValue:String;
         
         var listBase:ListBase = ListBase(master);
         
         var index:int = listBase.selectedIndex;
         if (childID == 0)
         {
             if (index > -1)
             {
                 var item:Object = getItemAt(index);
     
                 if (item is String)
                 {
                     accValue = item + " " + (index + 1) + " of " + listBase.dataProvider.length;
                 }
                 else
                 {
                     accValue = listBase.itemToLabel(item) + " " + (index + 1) +
                                " of " + listBase.dataProvider.length;
                 }
             }
         }
     
         return accValue;
     }

Zwraca tablicę zawierającą identyfikatory (liczby całkowite bez znaku) wszystkich elementów potomnych w obiekcie AccessibilityImplementation.

Tablica może mieć zerową długość. Kolejność identyfikatorów w tablicy powinna być zgodna z porządkiem logicznym elementów podrzędnych, którym te identyfikatory są przypisane. Jeśli obiekt AccessibilityImplementation może zawierać elementy podrzędne, ta metoda jest wymagana; w przeciwnym razie nie należy jej implementować.

Przypisując elementom podrzędnym identyfikatory, należy stosować system gwarantujący unikatowość identyfikatorów w ramach każdej instancji klasy AccessibilityImplementation. Identyfikatory elementów podrzędnych nie muszą być kolejnymi liczbami całkowitymi, a ich wartości nie muszą odzwierciedlać kolejności logicznej elementów podrzędnych. Należy zadbać o to, aby identyfikatory elementów podrzędnych nie były używane ponownie; jeśli element podrzędny zostanie usunięty, jego identyfikator nie powinien być już nigdy używany w danej instancji klasy AccessibilityImplementation. Należy zwrócić uwagę, że ze względu na specyfikę kodu programu Flash Player użycie identyfikatorów elementów o wartościach większych niż jeden milion może spowodować niepożądane działanie programu.

     override public function getChildIDArray():Array
     {
         var childIDs:Array = [];
     
         if (ListBase(master).dataProvider)
         {
             var n:uint = ListBase(master).dataProvider.length;
             for (var i:int = 0; i < n; i++)
             {
                 childIDs[i] = i + 1;
             }
         }
         return childIDs;
     }
     

Zwraca wartość true albo false, wskazując, czy obiekt tekstowy o obwiedni określonej przez parametry x, y, width i height powinien być uznawany za etykietę składnika reprezentowanego przez ten obiekt AccessibilityImplementation.

Współrzędne x i y są liczone względem lewego górnego rogu składnika, do którego ma zastosowanie obiekt AccessibilityImplementation, i mogą być ujemne. Wszystkie współrzędne są wyrażone w pikselach stołu montażowego.

Ta metoda umożliwia uwzględnienie składników z ułatwieniami dostępu w automatycznym wyszukiwaniu przez program Flash Player relacji między składnikami a etykietami, co pozwala na określenie nazwy obiektu w postaci tekstu zewnętrznego względem obiektu. Te metoda została udostępniona, ponieważ zakłada się, że kryteria rozpoznawania etykiet będą różne dla poszczególnych składników. Jeśli metoda ta zostanie zaimplementowana, należy dążyć do stosowania kryteriów geometrycznych podobnych do tych, jakie stosowane są w kodzie odtwarzacza w odniesieniu do przycisków i pól tekstowych. Są to następujące kryteria:

• Za etykietę przycisku uznaje się każdy tekst w całości znajdujący się wewnątrz przycisku.
• Za etykietę pola tekstowego uznaje się każdy tekst znajdujący się blisko pola, nad nim, wyrównany do lewej; albo każdy tekst znajdujący się blisko pola, po jego lewej stronie.

Jeśli składnik reprezentowany przez obiekt AccessibilityImplementation nigdy nie powinien uczestniczyć w automatycznym przypisywaniu etykiet, nie należy implementować metody isLabeledBy. Będzie to równoznaczne ze zwracaniem zawsze wartości false. Jednym z przypadków, w których nie należy implementować metody isLabeledBy, jest sytuacja, gdy obiekt AccessibilityImplementation ma nazwę przypisaną przez autora wewnątrz składnika (patrz opis metody get_accName zamieszczony powyżej).

Należy zwrócić uwagę, że ta metoda nie bazuje na żadnej z metod interfejsu IAccessible; jest charakterystyczna dla środowiska Flash.

Parametry