Tekst źródłowy strony Dodawanie manipulatorów do kabin na podstawie istniejących już komend

== Wstęp ==
Każdy przełącznik/dźwignia/przycisk w maszynie to tak naprawdę wskaźnik/miernik/lampka. Bezpośrednie klikanie na takie coś nie daje żadnego efektu. Aby wszystko działało prawidłowo, tzn. aby przyciski się animowały i reagowały na akcje gracza, należy podjąć kilka kroków opisanych w tym poradniku. Został on przygotowany tak, aby osoba znająca język c++ była w stanie samodzielnie dodać swój pierwszy przycisk, na podstawie istniejących już komend.

== Definicja przycisku ==
Zaczynamy od dodania TGauge (czyli naszego wskaźnika) w pliku Train.cpp i Train.h - najlepiej go od razu opisać za co odpowiada, aby ktoś później edytujący kod, wiedział za co dana zmienna odpowiada. Przykładowa definicja:
<code>TGauge ggPantValvesUpdate;</code>

W ten sposób tworzymy obiekt naszego przycisku. Trzeba go zainicjalizować. W tym celu w funkcji ```Update(double const Deltatime)``` dodajemy następujące linijki w odpowiednich sekcjach:
 <code>// obok wszystkich innych .Update dla innych wskaźników 
 ggPantValvesUpdate.Update();</code>

Pozostaje nam dopisać ten przycisk do funkcji przygotowującej kabinę, czyli ''set_cab_controls(int const Cab)'''
 <code>if (ggPantValvesUpdate.SubModel != nullptr)
 {
     ggPantValvesUpdate.PutValue(0.f);
 }</code>
Tym fragmentem kodu przypisujemy wartość 0 dla naszego wskaźnika jednocześnie go inicjalizując. Pozostaje jeszcze funkcja clear_cab_controls() która ma za zadanie  zresetować kabinę (używane jest to w momencie gdy zmieniamy kierunek w którym jedziemy, czy przemieszczając się z jednego pojazdu do innego). Oto przykładowy wpis:
 <code>ggPantValvesUpdate.Clear();</code>

Teraz dodajemy interakcje za pomocą myszki. Przycisk/przełącznik który chcemy dodać w tym przykładzie chcemy żeby był definiowany w pliku mmd (sekcja cabXdefinition) kluczem '''pantvalvesupdate_bt:'''.  Otwieramy plik '''drivermouseinput.cpp''' i szukamy funkcji '''default_bindings()'''. Na samym jej początku znajduje się mapa przypisań kryjąca się pod nazwą '''m_buttonbindings'''. Dodajemy do niej jakie komendy chcemy wykonać wciskając lewy lub prawy przycisk myszki. W naszym przykładzie wpis będzie wyglądał następująco:
 <code>{ "pantvalvesupdate_bt:", { // string definiujący klucz w mmd przycisku/przełącznika dla którego chcemy wykonywać akcję
 user_command::pantographvalvesupdate, // komenda wykonywana wciskając LPM
 user_command::none}}, // komenda wykonywana wciskając PPM - w tym przypadku nie podejmuje zadnej akcji</code>

'''Uwaga:''' Należy pamiętać o dwukropku na końcu klucza,
Lista dostępnych komend zawarta jest w ENUMie '''user_command'''. Można również sprawdzić wywoływaną komendę przez istniejący przycisk za pomocą symulatora, klikając na niego, a następnie patrząc w okienko konsoli zobaczyć jaka komenda została wywołana. Jej treść znajduje się pomiędzy nawiasami kwadratowymi [].

== Podpowiedzi po najechaniu myszką ==

Aby graczowi było łatwiej się zorientować, co za co odpowiada, symulator używa systemu podpowiedzi. Jak można się domyślić, naszemu przyciskowi należy również zdefiniować tzw. hint. Robimy to w pliku '''translation.cpp''' dodając w funkcji '''label_cab_control(std::string const &Label)''' w mapie '''cabcontrols_labels''' tekst podpowiedzi. W tym przykładzie będzie to:
 <code>{ "pantvalvesupdate_bt:",  // klucz mmd naszego przycisku
  STRN("selected pantographs up") } // tekst wyświetlany po najechaniu na przycisk</code>

'''Uwaga:''' Należy pamiętać o dwukropku na końcu klucza

== Animacja ==
Animacja przycisku odbywa się w funkcji wywoływanej komendy. Listę przypisań komend z ENUMa '''user_command''' do funkcji można znaleźć w mapie '''m_commandhandlers''' w pliku '''Train.cpp'''. Gdy znajdziemy funkcję odpowiadającą naszemu przyciskowi, przechodzimy do niej i dopisujemy linijkę aktualizującą nasz przycisk. Zanim jednak to zrobimy warto, omówić budowę funkcji '''OnCommand_*'''. Jak można zauważyć przyjmuje ona dwa parametry - '''Train''' oraz '''Command'''. Train zawiera odnośnik do pojazdu, do jego obiektu '''TTrain''', a Command kontekst w jakim funkcja została wywołana np. czy przycisk jest kliknięty, trzymany, puszczony, parametry, deltatime między wywołaniami, czy wywołano w trybie freefly (kamera F4), czy lokalizacja wywołania. Najważniejszym elementem będzie Command.action ponieważ dzięki niemu zabezpieczamy naszą funkcję przed zbyt dużą ilością wywołań. 

=== Omówienie budowy OnCommand_* ===
Omówmy przykładową funkcję:
 <code><nowiki>void TTrain::OnCommand_alarmchainenable(TTrain *Train, command_data const &Command)
 {
	if (Command.action == GLFW_PRESS) { 
         // pull
         Train->mvOccupied->AlarmChainSwitch(true);
         // visual feedback
         Train->ggAlarmChain.UpdateValue(1.0);
     }
 }<nowiki/></code>

Dla kogoś kto zna podstawy c++ to część może być zrozumiała. Mamy definicję funkcji OnCommand_alarmchainenable w klasie TTrain, mamy parametry Train zawierający pojazd z którego komenda została wywołana, oraz Command zawierający parametry.
Linijkę niżej widzimy warunek, który wykonuje się w momencie naciśnięcia klawisza/przycisku myszki, GLFW_PRESS to jedno z kilku dostępnych makr. Możemy skorzystać z:
* '''GLFW_PRESS''' - naciśnięcie
* '''GLFW_REPEAT''' - trzymanie
* '''GLFW_RELEASE''' - puszczenie

Kolejna linijka odnosi się do [[Mover|movera]] pojazdu wywołującego komendę oraz wywołuje funkcję '''AlarmChainSwitch''', która uruchamia hamulec bezpieczeństa np. w siódemkach klapa Ackermana.

Kolejna lnijka, tak jak komentarz wskazuje, odpowiada za animację przycisku w wywołującym pojeździe. Jest to przycisk podpisany jako '''ggAlarmChain''' i ustawia jego wartość na 1.0.

=== Dodawanie wpisu animacji ===
Na podstawie przycisku, który chcieliśmy dodać w poprzednich paragrafach, odpowiednią do tego funkcją będzie '''OnCommand_pantographvalvesupdate'''. W warunku <code>if (Command.action == GLFW_PRESS)</code> dopisujemy
 <code>Train->ggPantValvesButton.UpdateValue(1.0, Train->dsbSwitch);</code>.
Pierwszy parametr to wartość na jaką ustawiamy przycisk, a drugi to [[sound_source]]. Na razie nie będziemy się w to zagłębiać co to i jak działa, do przycisków w zupełności wystarczy '''Train->dsbSwitch'''. Po tym co zdefiniowaliśmy na ten moment mamy animację samego wciśnięcia. Trzeba dodać jeszcze animację odkliku. W tym celu dodajemy podaną wyżej linijkę, tym razem z parametrem 0.0 do warunku <code>if (Command.action == GLFW_RELEASE)</code>
W ten sposób zdefiniowaliśmy w pełni nasz przycisk i będzie on działał w symulatorze.