Blog o programowaniu w Silverlight i nie tylko.: kwietnia 2009

Jakiś czas temu wymyśliłem sobie malutki programik który będzie odliczał ustawiony czas. Ktoś by zapytał: po co to komu? Jednak jak się dobrze zastanowić, to taki "counter" czasu może być bardzo fajnym dodatkiem do wielu stron. Na pewno fajnie przypomni o nadchodzącej konferencji czy też spotkaniu, chociaż jestem przekonany że znajdzie się dla niego wiele innych ciekawych zastosowań :)

Wychodząc naprzeciw oczekiwaniom stworzyłem taki programik i umieściłem wraz z kodem źródłowym na codeplex-sie pod adresem: http://silverlightgadgets.codeplex.com/ (mam nadzieję że uda mi się tam także umieścić wiele innych "gadgetów")

Demo znajdziecie pod adresem (tak wiem, grafika wygląda tragicznie ;)):

http://wpierdalaj.pl/SWG/SilverlightCountDown/Run/SilverlightCountDownTimerExampleTestPage.html

Jak go użyć

Counter został stworzony tak aby był łatwo konfigurowalny i zgodny z wymaganiami wzorca Model-View-ViewModel (MVVM). Najłatwiej jest zwyczajnie:

Pobrać bibliotekę kontrolki (SilverlightCountDownTimer.dll) ze strony http://silverlightgadgets.codeplex.com/,
Dołączyć ją do rozwijanego projektu (Add References),
Umieścić w kodzie:

<UserControl x:Class="SilverlightCountDownTimerExample.MainPage"
  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
  xmlns:timeCounter="clr-namespace:SilverlightTimer assembly=SilverlightCountDownTimer"        
  Width="200" Height="100">
  <Grid x:Name="LayoutRoot" Background="Transparent">
      <timeCounter:SilverlightTimerControl EventDescription="Time to New Year Party"
      EventTime="2010-01-01 00:00" />
  </Grid>
</UserControl>

Tak jak widzimy w przykładzie, wystarczy wstawić kontrolkę i ustawić podstawowe parametry aby odliczanie ruszyło.

Parametry

Do dyspozycji mamy następujące parametry konfiguracji kontrolki:

EventDescription – Tekst który wyświetli się pod odliczanym czasem. W tej wersji istnieje ograniczenie długości pola tekstowego jakie może pomieścić textbox.
EventTime – Data do której będzie odliczany czas.
EventTimeUrl – Adres pliku tekstowego który zawiera datę. Ten parametr umożliwia dynamiczne modyfikowanie daty bez ingerencji w kod aplikacji. Wystarczy że zmienimy datę w pliku, a counter zacznie odliczać czas do nowej daty. Przykładowy plik z datą: http://wpierdalaj.pl/SWG/date.txt. Uwaga, jeśli ustawimy także parametr "EventTime", "EventTimeUrl" zostanie pominięty. Parametr"EventTime" ma pierwszeństwo przed "EventTimeUrl". Należy także zwrócić uwagę czy plik z datą jest dostępny dla odwołań z zewnątrz (patrz ustawienia Client Access Policy na blogu Tim Heuera)
CounterFinish – Event który zostanie wywołany gdy counter skończy odliczanie. W ten sposób możemy zainicjalizować jakąś akcję w aplikacji gdy upłynie ustawion czas.
EventTimeCache – Ten parametr uruchamia funkcję cache'owania daty. Ma to zapobiec sytuacji nadmiernego odpytywania serwera (poprzez parametr EventTimeUrl) o datę do odliczania. Odpytanie jest mało kosztowne, a sama data to kilka bajtów, ale jeśli można odciążyć serwer, to warto skorzystać z tej możliwości. Domyślnie cache jest wyłączony, a jego czas ważności ustawiony na jeden dzień, po tym terminie counter sprawdzi czy ma aktualne dane.
EventTimeCacheDuration – Ta opcja zmienia domyślny czas cachowania daty. Jednostką jest dzień, a więc ustawienie tego parametru na wartość 40, sprawi że aplikacja przez 40 dni nie będzie aktualizować odliczanej daty.

Wszystkie wyżej wymienione parametry możemy także ustawiać bezpośrednio w kodzie i zmieniać w czasie działania kontrolki. Np.:

.XAML:

<timeCounter:SilverlightTimerControl x:Name="myCounter" />

.CS (C#):

myCounter.EventTime = new DateTime(1983, 12, 14, 0, 0, 0);
myCounter.EventDescription = "Moje Urodziny";

Ponieważ aplikacja wspiera pattern Model-View-ViewModel (MVVM), możliwe jest także ustawienie binding-u na w/w paramentry. Np.:

<timeCounter:SilverlightTimerControl x:Name="myCounter" EventTime="{Binding Path=EventTime}" />

Podłączenie aplikacji bez dotykania kodu i Visual Studio

Dla tych którzy nie mają ochoty na zabawę z Visual Studio, dostępna jest także opcja gotowej aplikacji konfigurowanej z poziomu kodu html. W pliku "HtmlVersion" znajduje się kompletny przykład takiej konfiguracji, a poniżej wycinek z pliku SilverlightCountDownTimerExampleTestPage.html:

<object data="data:application/x-silverlight-2,"
type="application/x-silverlight-2" width="100%" height="100%">
   <param name="source" value="ClientBin/SilverlightCountDownTimerExample.xap"/> 
   <param name="onerror" value="onSilverlightError" />
   <param name="background" value="white" />
   <param name="minRuntimeVersion" value="3.0.40307.0" />
   <param name="autoUpgrade" value="true" />

   <!--// EventTimeUrl will be ignored because EventTime is set-->
   <param name="initParams"
    value="EventDescription=Time to MIX 2010,
    EventTime=2010-03-15 08:00,
    EventTimeUrl=http://wpierdalaj.pl/SWG/date.txt,
    EventTimeCache=True,
    EventTimeCacheDuration=40"
   />

</object>

Aby uruchomić counter, nie musimy ustawiać wszystkich w/w parametrów. Jeśli coś nie działa, sprawdźcie czy nie zrobiliście błędu w zapisie. Niestety opcja "initParams" jest bardzo czuła na dodatkowe znaki oraz nie pozwala na znaki specjalne, np. cudzysłowy czy przecinki w ustawianych wartościach.

Dodatki

Jeśli chcemy aby counter był klikalny i np. przekierował osobę na inną stronę, wystarczy otoczyć go prostym Hiperlinkiem w kodzie XAML:

<HyperlinkButton NavigateUri="http://jacekciereszko.pl" TargetName="_blank" >
     <timeCounter:SilverlightTimerControl x:Name="myControl" />
</HyperlinkButton>

Wygląd

Na ten moment nie przewiduje dla "countera" skinsów ani wsparcia na zmianę grafiki. Powodem tego jest brak jakichkolwiek umiejętności graficznych, w związku z tym zakładam że każdy będzie sam w stanie korzystając z kodu źródłowego dostosować wygląd aplikacji do swoich potrzeb.

Jeśli znajdzie się ktoś kto chciałbym coś ładnego namalować i się tym podzielić, chętnie dodam to do projektu.

Podsumowanie

Proszę piszcie jeśli macie jakieś propozycje lub zastrzeżenia, będę starał się ulepszać na bierząco "odliczacza" czasu :) Na razie planowany jest downgrade do wersji Silverlight 2.0.

Strona projektu: http://silverlightgadgets.codeplex.com/

Pozdrawiam,

Jacek Ciereszko