'**********************************************************************************************************
' Nazwa:                unikatowaNazwaArkusza
' Autor:                mielk | 2013-04-16
'
' Opis:                 Funkcja sprawdza czy w podanym pliku Excela znajduje się już arkusz o podanej
'                       nazwie. Jeżeli tak, do nazwy arkusza doczepiana jest liczba porządkowa w nawiasie
'                       i w takiej postaci jest ona zwracana jako wynik działania funkcji.
'
' Argumenty:
'   plik                Obiekt typu Workbook. Plik Excela, dla którego podana nazwa ma być sprawdzona pod
'                       kątem unikalności.
'   nazwa               String. Nazwa arkusza, która jest sprawdzana pod kątem unikalności w podanym pliku
'                       Excela.
'
' Zwraca:
'   String              Jeżeli w podanym pliku nie ma jeszcze arkusza o podanej nazwie, nazwa ta zwracana
'                       jest w oryginalnej postaci, chyba że nie jest to prawidłowa nazwa dla arkusza
'                       Excela (np. jest za długa lub zawiera niedozwolone znaki) - w takiej sytuacji
'                       zwracana jest nazwa przetworzona do postaci prawidłowej nazwy arkusza (dzięki
'                       wykorzystaniu funkcji poprawnaNazwaArkusza).
'
'                       Jeżeli w podanym pliku występuje już arkusz o podanej nazwie, zwracana jest ta
'                       nazwa z dopisanym numerem porządkowym (również po wcześniejszym dostosowaniu jej
'                       do wymagań, jakie są stawiane przed nazwami arkuszy). Jeżeli po dopisaniu liczby
'                       porządkowej, otrzymana nazwa przekroczy maksymalną dopuszczalną długość nazwy
'                       arkusza (31 znaków), obcięta zostaje odpowiednia część oryginalnej nazwy.
'
'                       Przykład:
'                       -----------------------------------------------------------------------------------
'                       Dla określonego pliku sprawdzana jest unikalność nazwy arkusza dane.
'                       * Jeżeli w pliku nie ma jeszcze arkusza o takiej nazwie, funkcja zwróci oryginalną
'                       wartość - dane.
'                       * Jeżeli w pliku jest już arkusz o takiej nazwie, zwrócona zostanie nazwa dane (1).
'                       * Jeżeli również taka nazwa występuje już w pliku, funkcja zwróci nazwę
'                         dane (2), itd.
'
'
' Wyjątki:
'   NiedostepnyPlik                 Zwracany, kiedy niemożliwe jest odniesienie się do pliku Excela
'                                   podanego jako argument wejściowy [plik] (np. został on zamknięty).
'
'
' --- Zmiany ----------------------------------------------------------------------------------------------
' 2013-04-16        mielk           Utworzenie funkcji.
'**********************************************************************************************************
Public Function unikatowaNazwaArkusza(plik As Excel.Workbook, nazwa As String) As String
    Const NAZWA_METODY As String = "unikatowaNazwaArkusza"
    '------------------------------------------------------------------------------------------------------
    Const MAX_DLUGOSC As Integer = 31
    '------------------------------------------------------------------------------------------------------
    Dim arkusz As Excel.Worksheet
    Dim strTempNazwa As String
    Dim intIterator As Integer
    Dim intLicznikZnakow As Integer
    '------------------------------------------------------------------------------------------------------


    'Sprawdź czy podana nazwa jest poprawną nazwą arkusza. Jeżeli nie, przetwórz ją do poprawnej --------|
    'postaci, za pomocą funkcji poprawnaNazwaArkusza                                                    '|
    strTempNazwa = poprawnaNazwaArkusza(nazwa)                                                          '|
    unikatowaNazwaArkusza = strTempNazwa                                                                '|
    '----------------------------------------------------------------------------------------------------|


    'Sprawdź, czy plik, dla którego będziemy sprawdzać unikatowość podanej nazwy, nie jest zamknięty.----|
    If Not czyPrawidlowyPlik(plik) Then GoTo NiedostepnyPlik                                            '|
    '----------------------------------------------------------------------------------------------------|


    'Funkcja próbuje znaleźć w podanym pliku arkusz o danej nazwie. W przypadku błędu tej operacji ------|
    '(a więc sytuacji, gdy w pliku nie ma jeszcze takiego )arkusza, wykonywanie kodu przenoszone        '|
    'jest do etykiety unikatowaNazwa, znajdującej się tuż przed wyjściem z funkcji, co w praktyce       '|
    'oznacza zakończenie jej działania i zwrócenie oryginalnej wartości bez dopisywania jakichkolwiek   '|
    'oznaczeń (ewentualnie przetworzonej do postaci prawidłowej nazwy arkusza, jeżeli podana nazwa      '|
    'wcześniej nie spełniała wymogów poprawności).                                                      '|
    On Error GoTo UnikatowaNazwa                                                                        '|
    Set arkusz = plik.Worksheets(strTempNazwa)                                                          '|
    On Error GoTo 0                                                                                     '|
    '----------------------------------------------------------------------------------------------------|


    'Jeżeli w pliku znaleziony został arkusz o podanej nazwie, niezbędna jest jej modyfikacja -----------|
    'poprzez dopisanie odpowiedniej liczby.                                                             '|
    If Not arkusz Is Nothing Then                                                                       '|
                                                                                                        '|
        'Powtarzaj tę operację tak długo, jak istnieje arkusz z podaną nazwą. -----------------------|  '|
        Do                                                                                          '|  '|
            intIterator = intIterator + 1                                                           '|  '|
            unikatowaNazwaArkusza = strTempNazwa & " (" & intIterator & ")"                         '|  '|
                                                                                                    '|  '|
            'Funkcja sprawdza czy wygenerowana nazwa nie przekracza maksymalnej dopuszczalnej ---|  '|  '|
            'długości (zdefiniowanej przez stałą MAX_DLUGOSC) i ewentualnie skraca tę nazwę     '|  '|  '|
            'poprzez obcięcie znaków z prawej części oryginalnej nazwy.                         '|  '|  '|
            '(the maximum length is defined by constant MAX_DLUGOSC).                           '|  '|  '|
            intLicznikZnakow = VBA.Len(unikatowaNazwaArkusza)                                   '|  '|  '|
            If intLicznikZnakow > MAX_DLUGOSC Then                                              '|  '|  '|
                unikatowaNazwaArkusza = VBA.Left$(strTempNazwa, _
                   VBA.Len(strTempNazwa) - intLicznikZnakow + MAX_DLUGOSC) & _
                   " (" & intIterator & ")"                                                     '|  '|  '|
            End If                                                                              '|  '|  '|
            '------------------------------------------------------------------------------------|  '|  '|
                                                                                                    '|  '|
                                                                                                    '|  '|
            'Funkcja ponownie sprawdza czy w danym pliku występuje arkusz o podanej nazwie, -----|  '|  '|
            'z tym że nazwa ta, po dopisaniu do niej odpowiedniej liczby porządkowej, ma        '|  '|  '|
            'teraz inną postać.                                                                 '|  '|  '|
            'Jeżeli również arkusz o takiej, zmodyfikowanej nazwie znajduje się już w tym       '|  '|  '|
            'pliku, nazwa jest ponownie modyfikowana poprzez zastąpienie dopisanej do niej      '|  '|  '|
            'liczby kolejną liczbą całkowitą np. zamiast nazwy dane (1), testowana będzie       '|  '|  '|
            'nazwa dane (2).                                                                    '|  '|  '|
            'Procedura powtarzana jest tak długo, aż funkcja natrafi na unikatową nazwę.        '|  '|  '|
            On Error GoTo UnikatowaNazwa                                                        '|  '|  '|
            Set arkusz = plik.Worksheets(unikatowaNazwaArkusza)                                 '|  '|  '|
            On Error GoTo 0                                                                     '|  '|  '|
            '------------------------------------------------------------------------------------|  '|  '|
                                                                                                    '|  '|
        Loop Until arkusz Is Nothing                                                                '|  '|
        '--------------------------------------------------------------------------------------------|  '|
                                                                                                        '|
    End If                                                                                              '|
    '----------------------------------------------------------------------------------------------------|



'==========================================================================================================
PunktWyjscia:
    Exit Function

'----------------------------------------------------------------------------------------------------------
NiedostepnyPlik:
    'Obsługa błędu dla sytuacji, kiedy niemożliwe jest odniesienie się do podanego pliku [plik] (np. z
    'powodu jego zamknięcia).

    GoTo PunktWyjscia


'----------------------------------------------------------------------------------------------------------
UnikatowaNazwa:
    'Aktualna wartość zmiennej [nazwa] jest unikatowa i może być zwrócona.

End Function






'**********************************************************************************************************
' Nazwa:                poprawnaNazwaArkusza
' Autor:                mielk | 2012-03-26
'
' Opis:                 Funkcja sprawdza czy przekazany ciąg tekstowy odpowiada wymogom, jakie muszą
'                       spełniać nazwy arkuszy Excela:
'                           *   nie może być pusta,
'                           *   jej długość nie może przekraczać 31 znaków,
'                           *   nie może zawierać żadnego z niedozwolonych znaków : ? / \ * [ ]
'                       Jeśli podana nazwa nie spełnia któregoś z tych wymogów, jest ona odpowiednio
'                       dostosowywana.
'
' Argumenty:
'   name                Tekst sprawdzany pod kątem poprawności jako nazwa arkusza.
'
' Zwraca:
'   String              Podana nazwa przekształcona w taki sposób, by była prawidłową nazwą arkusza Excela.
'                           *   Jeżeli wejściowa nazwa spełnia wymogi prawidłowej nazwy arkusza, jest ona
'                               zwracana w całości w nienaruszonym stanie.
'                           *   Jeżeli nazwa wejściowa jest pusta, zwracany jest znak podkreślenia (_).
'                           *   Jeżeli nazwa wejściowa jest dłuższa niż dopuszczalne 31 znaków, nadmiarowa
'                               część nazwy zostaje ucięta.
'                           *   Jeżeli nazwa wejściowa zawiera niedopuszczalne znaki : ? / \ * [ ], są one
'                               z niej usuwane.
'
'
' --- Zmiany ----------------------------------------------------------------------------------------------
' 2012-03-26        mielk           Utworzenie funkcji.
'**********************************************************************************************************
Public Function poprawnaNazwaArkusza(name As String) As String
    Const NAZWA_METODY As String = "poprawnaNazwaArkusza"
    '------------------------------------------------------------------------------------------------------
    Const NIEDOZWOLONE_ZNAKI As String = ":?/\*[]"
    '------------------------------------------------------------------------------------------------------
    Dim intZnak As Integer
    Dim strZnak As String
    Dim strNiedozwoloneZnaki As String
    '------------------------------------------------------------------------------------------------------



    'Funkcja przechodzi przez wszystkie znaki w oryginalnej nazwie i usuwa z niej niedozwolone znaki. ---|
    For intZnak = 1 To VBA.Len(name)                                                                    '|
        strZnak = VBA.Mid$(name, intZnak, 1)                                                            '|
                                                                                                        '|
        '--------------------------------------------------------------------------------------------|  '|
        If VBA.InStr(1, strNiedozwoloneZnaki, strZnak) = 0 Then                                     '|  '|
            poprawnaNazwaArkusza = poprawnaNazwaArkusza & strZnak                                   '|  '|
        End If                                                                                      '|  '|
        '--------------------------------------------------------------------------------------------|  '|
                                                                                                        '|
    Next intZnak '---------------------------------------------------------------------------------------|


    'Sprawdza długość nazwy arkusza po usunięciu niedozwolonych znaków. Jeżeli jest ona za długa, -------|
    'nadmiarowe znaki są ucinane.                                                                       '|
    Select Case VBA.Len(poprawnaNazwaArkusza)                                                           '|
        Case Is > 31                                                                                    '|
            poprawnaNazwaArkusza = VBA.Left$(poprawnaNazwaArkusza, 31)                                  '|
        Case 0                                                                                          '|
            poprawnaNazwaArkusza = "_"                                                                  '|
    End Select '-----------------------------------------------------------------------------------------|

End Function




'**********************************************************************************************************
' Nazwa:                czyPrawidlowyPlik
' Autor:                mielk | 2013-04-25
'
' Opis:                 Funkcja sprawdzająca czy podany plik Excela jest prawidłowy i można odwoływać się
'                       do jego właściwości i metod bez obawy, że zostanie wygenerowany błąd.
'
'                       Funkcja jest bardzo pomocna, ponieważ pozwala uniknąć błędu
'                       Run-time error '-2147221080 (800401a8)': Automation error.
'                       Błąd ten jest generowany w sytuacji, kiedy kod próbuje się odnieść do właściwości
'                       lub metody skoroszytu Excelu, ale plik ten został wcześniej zamknięty.
'
' Argumenty:
'   wkb                 Sprawdzany skoroszyt Excela.
'
' Zwraca:
'   Boolean             True - jeżeli sprawdzany skoroszyt jest prawidłowy i bez obaw można się odnosić do
'                               jego właściwości i metod.
'                       False - jeżeli podany skoroszyt jest nieprawidłowy (zazwyczaj przyczyną jest fakt,
'                               że plik ten został wcześniej zamknięty).
'
'
' --- Zmiany ----------------------------------------------------------------------------------------------
' 2013-04-25        mielk       Utworzenie funkcji.
'**********************************************************************************************************
Public Function czyPrawidlowyPlik(wkb As Excel.Workbook) As Boolean
    Const NAZWA_METODY As String = "czyPrawidlowyPlik"
    '------------------------------------------------------------------------------------------------------
    Dim strNazwaSkoroszytu As String
    '------------------------------------------------------------------------------------------------------
    
    On Error Resume Next
    strNazwaSkoroszytu = wkb.name
    
    'Jeżeli nazwa podanego pliku została przypisana do zmiennej [strNazwaSkoroszytu], oznacza to, że ten
    'skoroszyt jest prawidłowy i można odwoływać się do jego właściwości bez obawy o pojawienie się błędów.
    czyPrawidlowyPlik = VBA.Len(strNazwaSkoroszytu)
    
End Function