Mała Hydra

Przez Małą Hydrę rozumiemy mechanizm, który pozwala na ukrycie, wyłączenie lub ustawienie wymagalności dla kontrolek na istniejących oknach. Callbacki zarówno Małej jak i Dużej Hydry są widoczne na Liście dodatków. Lista ta umożliwia importowanie i eksportowanie callbacków, zmianę ich stanu, dodawanie, usuwanie oraz edycję.

Na liście dodatków znajdują się następujące przyciski:

Nowy dodatek – użycie funkcji rozpocznie proces dodawania nowego callbacka.

Importuj – funkcja umożliwia zaimportowanie zdefiniowanego callbacka ze wskazanej lokalizacji.

Eksportuj – funkcja umożliwia wyeksportowanie callbacka do wskazanej lokalizacji.

Odśwież – odświeżenie listy dodatków.

Odśwież w programie – funkcja odświeżania w całym programie, np. w przypadku usunięcia callbacka, zostanie on usunięty ze struktury firmy i innych obiektów w systemie dopiero po jej użyciu.

Dodaj – funkcja aktywna po dodaniu callbacka. Umożliwia jego szczegółowe zdefiniowanie.

Edytuj – umożliwia edycję zdefiniowanego callbacka.

Usuń – usuwa callbacka zaznaczonego na liście.

Aby dodać nowy dodatek Małej Hydry należy uruchomić funkcję Nowy dodatek. Zostanie podniesione okno Edycja dodatku.

Nazwa – w polu należy wprowadzić nazwę callbacka.

Wersja – wersja „Hydry”, w jakiej został utworzony callback; pole wypełniane jest automatycznie.

Przeznaczony dla wersji – wersja systemu Comarch ERP XL, w której callback będzie funkcjonował; pole wypełniane automatycznie.

Autor – autor callbacka; pole wypełniane automatycznie – wartością wprowadzaną domyślnie będzie zalogowany operator.

Data utworzenia – data utworzenia callbacka; pole wypełniane automatycznie.

Data dodania – data dodania callbacka do systemu; pole wypełniane automatycznie.

Operator – operator dodający callback do systemu; pole wypełniane automatycznie.

Stan – zaznaczenie wybranej opcji zadecyduje o aktywności callbacka w systemie. Aby callback funkcjonował w systemie, musi mieć zaznaczoną opcję: Aktywny.

Opis – w polu można wprowadzić opis callbacka.

Aby skonfigurować callbacka należy zaznaczyć dodatek i uruchomić funkcję Dodaj. W efekcie zostanie podniesione okno Edycja grupy procedur. W tym miejscu istnieje możliwość zdefiniowania dodatkowego warunku, na zakładanym callbacku. Warunek musi być zdefiniowany zgodnie ze składnią języka C# i musi zwracać wartość logiczną. W przypadku zwrócenia wartości true callback zostanie wykonany, w przypadku zwrócenia wartości false działanie callbacka zostanie zablokowane. W programie możemy definiować dwa rodzaje złożonych warunków callbacka:

Warunek oparty o zmienne słownikowe – warunek można skonstruować w oparciu o zmienne zawarte w ConfigurationDictionary.

Warunek oparty o bufor tabeli – warunek może być oparty o dane zawarte w buforze tabeli.

W ostatnim kroku należy zdefiniować zmienioną obsługę kontrolek. W tym celu należy na liście dodatków zaznaczyć dodaną procedurę i wywołać funkcję Dodaj. Zostanie podniesione okno Edycja akcji na kontrolce. W tym miejscu należy wskazać za pomocą znacznika odpowiednią kontrolkę na oknie, a następnie zdefiniować właściwą akcję:

Ukryj – ukrycie kontrolki na oknie

Dezaktywuj – dezaktywacja kontrolki na oknie

Wymagaj – ustawienie wymagalności kontrolki – nie będzie możliwe zamknięcie okna do czasu wprowadzenia wartości w kontrolce.

Pogrub – pogrubia czcionkę etykiety (pogrubiona czcionka zwykle służy do wizualnego oznaczenia pól wymaganych na formularzu)

Aby dodatek był aktywny w systemie należy go dodać do właściwego centrum w strukturze praw. W tym celu należy uruchomić okno Edycja struktury firmy i dodać zdefiniowanego callbacka na zakładce Dodatki.

Duża Hydra – informacje ogólne

Callbacki

Callbacki Dużej Hydry są mechanizmem, który służy do dodawania nowej funkcjonalności, bez potrzeby modyfikacji binariów programu. Od strony technicznej callbacki są zrealizowane jako plik dll eksportujący określony zestaw funkcji, podzielonych na funkcje plikowe i okienkowe.

Funkcje plikowe są wywoływane przez program podczas uruchamiania lub zamykania formatki – wówczas każda akcja użytkownika powoduje wywołanie pary zdarzeń: poprzedzających akcję i następujących po niej. Callbacki z tej grupy są najczęściej wykorzystywane do kontroli poprawności zapisywanych danych oraz do zaawansowanej kontroli uprawnień operatora.

Funkcje okienkowe są wykorzystywane w celu modyfikacji wyglądu i zachowania formatek. Składają się na nie trzy funkcje: wywoływane podczas inicjalizacji okna, przy każdym zdarzeniu okna oraz przed zamknięciem okna. Callbacki z tej grupy są najczęściej wykorzystywane do ukrywania lub uniemożliwiania edycji niektórych pól na formatkach lub do dodawania elementów interfejsu.

Zdarzenia obu grup są bardzo często używane łącznie.

Kod obsługujący zdarzenia należy umieścić w specjalnie przygotowanym module .NET’owym. Moduł taki musi zostać opisany za pomocą atrybutu CallbackAssemblyDescription w następujący sposób:

Przygotowanie Callbacka

[assembly:CallbackAssemblyDescription(“Nazwa callbacka”,”Opis callbacka”,”Autor callbacka”,”wersja callbacka”,”wersja systemu, dla której callback jest przeznaczony”,”data utworzenia callbacka w formacie dd-mm-rrrr”)]

Aby obsłużyć zdarzenia plikowe i okienkowe, należy dodać do modułu publiczną klasę dziedziczącą po klasie Callback, zdefiniowaną w assembly CdnHydra.dll. Klasę taką należy opisać atrybutem SubscribeProcedure w następujący sposób:

[SubscribeProcedure(Procedura z enumeracji Procedures,”Opis subskrypcji”)]

Klasa Callback jest abstrakcyjna, więc do skompilowania assembly będzie konieczne zdefiniowanie metod Init i Cleanup. Zdefiniowanie tych metod umożliwia użytkownikowi wykonanie kodu odpowiednio inicjującego i kończącego pracę z procedurą. Uwaga – nie należy umieszczać takiego kodu wewnątrz konstruktora ani metody Dispose, ponieważ jedna instancja klasy może być wykorzystywana wielokrotnie (każde kolejne uruchomienie przez użytkownika procedury będzie powodowało uruchomienie metody Init, ale nie konstruktora, podobnie z metodą Cleanup). W metodzie Init należy określić zainteresowanie zdarzeniami w procedurze. W przypadku zdarzeń plikowych subskrypcja powinna mieć postać:

AddFileActionSubscription(bool BeforeAction,

FileActionTypes ActionType,

FileActionDelegate ActionDelegate)

gdzie

BeforeAction – określa czy obsługa ma być wywoływana przed czy po zdarzeniu

FileActionTypes – określa typ zdarzenia plikowego, którego dotyczy subskrypcja

ActionDelegate – określa delegat wywoływany w odpowiedzi na zdarzenie

W przypadku zdarzeń okienkowych subskrypcja powinna mieć postać:

AddSubscription(bool BeforeHandling,

int ControlId,

Events EventId,

TakeEventDelegate EventDelegate)

gdzie

BeforeHandling – określa czy obsługa ma być wywoływana przed czy po zdarzeniu

ControlId – określa ID kontrolki (wartość 0 w przypadku ID okna)

EventId – określa zdarzenie, którego dotyczy subskrypcja

EventDelegate – określa delegat wywoływany w odpowiedzi na zdarzenie

Subskrypcje na zdarzenia mogą zostać usunięte za pomocą instrukcji:

RemoveFileActionSubscription(bool BeforeAction,

FileActionTypes ActionType,

FileActionDelegate ActionDelegate)

RemoveSubscription(bool BeforeHandling,

int ControlId,

Events EventId,

TakeEventDelegate EventDelegate)

Deklaracje delegatów dla zdarzeń plikowych i okienkowych powinny mieć odpowiednio postać:

public delegate bool FileActionDelegate (Procedures ProcedureId,

GID GID,

ADODB._Recordset Attributes);

gdzie

ProcedureId – id procedury, której dotyczy zdarzenie

GID – identyfikator rekordu, którego dotyczy zdarzenie

Attributes – zestaw atrybutów powiązanych z edytowanym rekordem

public delegate bool TakeEventDelegate (Procedures ProcedureId,

int ControlId,

Events EventId);

gdzie

ProcedureId – id procedury, której dotyczy zdarzenie

ControlId – id kontrolki, której dotyczy zdarzenie

EventId – id zdarzenia

Kod znajdujący się w callbacku ma dostęp do kontekstu, w którym został uruchomiony za pośrednictwem własności klasy ConfigurationManager. W ramach tej klasy są przechowywane następujące informacje:

– Baza string

– BazaHurtowni string

– BazaOLAP string

– Centra ADODB._Recordset

– DomyslnyMagazynSprzedazy string

– DomyslnyMagazynZakupu string

– DomyslnyRejestrBankowy string

– DomyslnySkladCelny string

– IdCentrumKosztowego int

– IdCentrumPodleglosciowego int

– IdCentrumWlasciwego int

– IdFirmy int

– KasaTransakcjiGotowkowych string

– KatalogProgramu string

– KoniecOkresuObrachunkowego datetime

– KontoDostawcow string

– KontoOdbiorcow string

– LoginZintegrowany bool

– MagazynDocelowyKompletacji string

– Magazyny ADODB._Recordset

– MagazynZrodlowyKompletacji string

– NumerOperatora int

– PieczatkaEmail string

– PieczatkaMiasto string

– PieczatkaNazwa string

– PieczatkaNIP string

– PieczatkaNIPPrefiks string

– PoczatekOkresuObrachunkowego datetime

– RabatyOdCeny bool

– RejestryBankowe ADODB._Recordset

– SciezkaWStrukturze string

– Serie ADODB._Recordset

– SerieOddzialowe ADODB._Recordset

– Serwer string

– SerwerOLAP string

– TypNaliczaniaMarzy Hydra.TypMarzy

– TypyKlasAtrybutow ADODB._Recordset

– WalutaSystemowa string

– Waluty ADODB._Recordset

Procedury HASPa:

– HASPDataAplikacji datetime

– HASPDataDealera datetime

– HASPLicencje ADODB._Recordset

– HASPLiczbaBaz int

– HASPNazwaUzytkownika string

– HASPNumerBazyDanych int- HASPNumerKlucza int

– HASPOpcje int

– HASPPlatforma int

– HASPStanKlucza int

Operacje na kontrolkach

Kod znajdujący się w callbacku może wykonywać operacje na interfejsie (dodawać, przesuwać i ukrywać kontrolki, wypełniać je itp.) za pośrednictwem własności i metod klasy ClaWindow. Instancję klasy ClaWindow można uzyskać za pomocą metody GetWindow klasy Callback (w celu uzyskania głównego okna procedury) lub GetControl (w celu uzyskania kontrolki).

Klasa ClaWindow jest wykorzystywana do operowania na oknach i kontrolkach Clarionowych. Każda instancja klasy ClaWindow jest powiązana z kontrolką lub oknem, na którym operuje.

Kolekcja AllChildren przechowuje wszystkie kontrolki znajdujące się na oknie. Można ją wykorzystać do odnalezienia poszukiwanej kontrolki. Pozostałe własności klasy odpowiadają własnościom kontrolek Clarionowych, które zostały opisane w dalszej części biuletynu.

Zdarzenia do kontrolki mogą być wysyłane za pośrednictwem metody:

public void PostEvent(Events EventId)

gdzie:

EventId – identyfikator zdarzenia, które ma zostać wysłane do kontrolki

Bardzo często zdarzenia do kontrolki są wysyłane parami – po wysłaniu określonego zdarzenia wymagane jest wysłanie zdarzenia Accepted w celu zatwierdzenia wprowadzonej wartości.

Podstawowe zdarzenia dla kontrolek:

OpenWindow/JustAfterWindowOpening – otwarcie okna

ResizeWindow – zmiana wielkości okna

NewSelection – kliknięcie w spin, przejście do innej zakładki

Accepted – akceptacja wprowadzenia nowej wartości do pola (odpowiednik wyjścia z kontrolki za pomocą tabulatora), kliknięcie przycisku.

ScrollDown/ScrollUp – scrollowanie listy

Podstawowe kontrolki

Główne właściwości kontrolek

Visible – (true/false) – widoczność kontrolki

Disable – kontrolka nieaktywna

Skip – kontrolka jest pomijana podczas przechodzenia tabulatorem

TextRaw – tekst widoczny na kontrolce

Bounds – współrzędne kontrolki

FontSizeRaw – wielkość czcionki

FontColorRaw – kolor czcionki

BackgroundRaw – kolor tła

FontStyleRaw – format tekstu

LeftRaw/RightRaw/CenterRaw – wyrównywanie tekstu w kontrolce

TipRaw – tekst wyświetlany w tooltipie kontrolki

MsgRaw – opis wyświetlany w stopce okna podczas aktywności kontrolki

Box

Kontrolka typu Box definiuje ramkę na oknie (prostokątny obszar).

ColorRaw – kolor ramki

RoundRaw – zaokrąglenie ramki

FillRaw – kolor wypełnienia

LineWidthRaw – grubość ramki

Panel

Kontrolka typu Panel definiuje obszar na oknie.

BevelRaw – efekt 3D dla ramki

Image

Kontrolka typu Image pozwala umieścić rysunek na oknie.

TextRaw – ścieżka do pliku z rysunkiem

Button

Kontrolka typu Button dodaje przycisk na oknie

IconRaw – przypisanie ikony do przycisku np. “~EXPORT20.ICO”

ReqRaw – naciśnięcie przycisku spowoduje sprawdzenie czy wszystkie pola Entry na oknie, które mają ustawiony parametr Req są wypełnione. Jeżeli nie są wypełnione to kursor zostanie przeniesiony do odpowiedniego pola Entry.FlatRaw – określenie czy przycisk jest płaski (wymagane jest przypisanie ikony do przycisku)

ImmRaw – moment wyzwolenia akcji na kontrolce. W przypadku przekazania do właściwości wartości „1” akcja zostanie wywołana w momencie kliknięcia przycisku, ale przed zwolnieniem przycisku myszy. W przypadku przekazania wartości „0” akcja zostanie wykonana po naciśnięciu i zwolnieniu przycisku myszy.

TextRaw – etykieta przycisku

StdRaw – przypisanie do przycisku standardowej akcji

Menu

Kontrolka dodaje dodatkową opcję w Menu okna. Aby zbudować menu należy posłużyć się dwoma

typami kontrolek: Menu i Item. Poniżej zaprezentowano przykład działania Menu:

Group

Kontrolka pozwala zgrupować na oknie inne kontrolki. Możliwe jest narysowanie ramki dla grupy i nadanie jej nazwy.

BoxedRaw – czy ma być wyświetlana ramka dla grupy (0 – nie, 1 – tak)

TextRaw – nazwa grupy

Text

Kontrolka typu Text dodaje pole tekstowe na oknie.

ToolTipRaw – tekst w tooltipie

SkipRaw – pole jest ignorowane podczas przechodzenia między kontrolkami za pomocą przycisku

Tabulatora

ReadOnlyRaw – pole ma status „tylko do odczytu”

TextRaw – domyślna wartość w polu tekstowym

List

Kontrolka typu List dodaje listę na oknie.

FromRaw – wypełnienie listy wartościami gdzie kolejne rekordy powinny być oddzielone od siebie

znakiem |. Jeżeli taki znak ma zostać wpisany jako wartość pozycji to należy wpisać ||. Pustą wartość

można uzyskać wpisując | |

VScrollRaw – umieszczenie pionowego paska przewijania na liście

FormatRaw – zdefiniowanie kolumn listy

SelectedRaw – numer zaznaczonego elementu na liście

Progress

Kontrolka Progress definiuje pasek postępu. Określenie postępu dla kontrolki określa się za pomocą parametru ProgressRaw.

Region

Kontrolka typu Region dodaje „interaktywny” obszar (Panel) na oknie.

ImmRaw – ustawienie parametru pozwala na obsługę zdarzeń typu MouseIn/MouseOut. Ponieważ właściwość może mieć wpływ na prędkość otwierania formatki należy ją definiować jedynie w przypadku wykorzystania dodatkowych zdarzeń.

DragIDRaw/DropIDRaw – obsługa zdarzeń typu Drag i Drop na obszarze.

Spin

RangeLowRaw – minimalna wartość dla kontrolki

RangeHighRaw – maksymalna wartość dla kontrolki

ScreenTextRaw – domyślna wartość dla kontrolki

FromRaw – lista możliwych wartości dla kontrolki oddzielonych od siebie znakiem |

TextRaw – określenie formatu pola

ValueRaw – określenie wartości domyślnej w polu (wymagane ustawienie UseRaw=”1”)

Zmiana wartości w kontrolce:

Runtime.WindowController.Change(kontrolka.Id, “wartość”)

.Check

Kontrolka typu Check pozwala na zwrócenie wartości z przedziału {0,1}

CheckedRaw – domyślna wartość kontrolki (1 – zaznaczony, 0 – odznaczony)

UseRaw – wartość w kontrolce przy odczycie

DropCombo

Kontrolka typu DropCombo jest połączeniem dwóch kontrolek: List oraz Entry. Kontrolka pozwala na wybranie wartości z listy jednocześnie umożliwiając dopisanie/zmianę wartości.

FromRaw – wypełnienie listy wartościami gdzie kolejne rekordy powinny być oddzielone od siebie znakiem |. Jeżeli taki znak ma zostać wpisany jako wartość pozycji to należy wpisać ||. Pustą wartość można uzyskać wpisując | |

VScrollRaw – umieszczenie pionowego paska przewijania na liście

DropRaw – liczba wierszy wyświetlanych na liście.

VCRRaw – pasek szybkiego przechodzenia po liście wartości

UprRaw – wpisanie wartości do pola będzie skutkowało automatyczną zmianą tekstu na duże znaki

SelectedRaw – wybranie pozycji na liście wartości

ScreenTextRaw – wpisanie wartości do pola entry

Droplist

Kontrolka typu Droplist pozwala na wybór wartości z rozwijanej listy bez możliwości jej edycji lub wprowadzania nowych wartości. Właściwości kontrolki w większości pozostają analogiczne jak na kontrolce Dropcombo.

Wyświetlanie komunikatów (dotyczy wyłącznie wersji SE)

Komunikat można wyświetlić za pomocą polecenia MessageBox.Show(string) po uprzednim odblokowaniu wątku. Właściwa obsługa wątków jest również konieczna na przykład w przypadku wywoływania okna .net’owego.

Przyklad

Runtime.WindowController.LockThread();

Runtime.WindowController.UnlockThread();

MessageBox.Show(“Tekst komunikatu”);