IEvents Library verze 0.4 (c)1998,1999 Štěpán Roh Požadavky --------- Allegro 3.0 + WIP Oct 25 nebo vyšší (tato verze byla testována s Allegro 3.1). Testováno pouze s DJGPP (vzhledem k mírné nekompatibilitě verzí Allegra pro DJGPP, Linux, X Window a DirectX zatím s ničím jiným nefunguje)! Obsah balíku ------------ ievents.txt - tato dokumentace license.txt.cz - licenční ujednání ChangeLog - změny mezi verzemi makefile - sestavovací soubor pro make ievents.h - hlavičkový soubor knihovny ievents.c - zdrojový kód knihovny test.c - testovací program Použití ------- Krok 1 : překlad knihovny - spuštění make v adresáři se zdrojovými soubory knihovny Krok 2 : použití knihovny - #include - přilinkování knihovny libievt.a Cíle pro make ------------- all nebo žádný cíl - přeloží a nainstaluje knihovnu a testovací program lib - přeloží knihovnu install - nainstaluje knihovnu libievt.a a soubor ievents.h do DJGPP adresáře test - přeloží testovací program test.exe clean - smaže meziprodukty překladu cleanall - smaže meziprodukty i produkty překladu uninstall - odinstaluje knihovnu a hlavičkový soubor Typy a definice --------------- informační definice : #define IEVT_NAME "IEvents Library" - jméno knihovny #define IEVT_COPY "(c)1998,1999 Stepan Roh" - copyright #define IEVT_MAJOR_VER 0 - hlavní číslo verze #define IEVT_MINOR_VER 4 - vedlejší číslo verze #define IEVT_VER_STR "0.4" - verze #define IEVT_FULL_NAME IEVT_NAME " " IEVT_VER_STR " " IEVT_COPY - celé jméno knihovny kód jednotlivých částí IEvents (pro IEVT_use_parts) : #define IEVT_USE_TIMER 0x01 - časovač #define IEVT_USE_KEYB 0x02 - klávesnice #define IEVT_USE_MOUSE 0x04 - myš (nutno s časovačem, doporučeno s klávesnicí) #define IEVT_USE_ALL 0xff - vše typy událostí : #define IEVT_NOTHING 0x0000 - žádná událost #define IEVT_KEY_DOWN 0x0001 - stisk klávesy (key) #define IEVT_KEY_UP 0x0002 - puštění klávesy (key) #define IEVT_KEY_REPEAT 0x0004 - autorepeat klávesy (key) #define IEVT_MOUSE_DOWN 0x0008 - stisk tlačítka myši (mouse) #define IEVT_MOUSE_UP 0x0010 - puštění tlačítka myši (mouse) #define IEVT_MOUSE_MOVE 0x0020 - posun myši (mouse) #define IEVT_MOUSE_CLICK 0x0040 - kliknutí (mouse) - jsou generovány i události DOWN a UP #define IEVT_MOUSE_DCLICK 0x0080 - dvojklik (mouse) - jsou generovány i události DOWN, UP a CLICK (jenom pro první stisk) #define IEVT_MOUSE_DRAG 0x0100 - táhnutí = posun s tlačítkem (mouse) - je generován i MOVE #define IEVT_MOUSE_REGION_ENTER 0x0200 - vstup do oblasti (mouse) #define IEVT_MOUSE_REGION_LEAVE 0x0400 - výstup z oblasti (mouse) #define IEVT_TIMER_TICK 0x0800 - časové znamení (timer) #define IEVT_MESSAGE 0x1000 - zpráva (msg) #define IEVT_USER 0x2000 - uživatelská událost (user) - volné jsou také všechny zbylé bity v int kombinace typů : #define IEVT_KEY_PRESS (IEVT_KEY_DOWN | IEVT_KEY_REPEAT) #define IEVT_KEY_LOW (IEVT_KEY_UP | IEVT_KEY_DOWN) #define IEVT_KEY_ALL (IEVT_KEY_LOW | IEVT_KEY_REPEAT) #define IEVT_MOUSE_BUTT (IEVT_MOUSE_DOWN | IEVT_MOUSE_UP) #define IEVT_MOUSE_REGION (IEVT_MOUSE_REGION_ENTER | IEVT_MOUSE_REGION_LEAVE) #define IEVT_MOUSE_LOW (IEVT_MOUSE_BUTT | IEVT_MOUSE_MOVE) #define IEVT_MOUSE_HIGH (IEVT_MOUSE_CLICK | IEVT_MOUSE_DCLICK | IEVT_MOUSE_DRAG | IEVT_MOUSE_REGION) #define IEVT_MOUSE_ALL (IEVT_MOUSE_LOW | IEVT_MOUSE_HIGH) #define IEVT_DEFAULT ~((unsigned int)IEVT_MOUSE_HIGH) #define IEVT_ALL ~((unsigned int)0) kódy zpráv (pro IEVT_MESSAGE v poli code) : #define IEVT_MSG_NOTHING 0 - žádná zpráva #define IEVT_MSG_TERMINATE -1 - TERMINATE zpráva (ukončení aplikace) speciální kódy příjemce zprávy (pro IEVT_MESSAGE v poli to) : #define IEVT_MSG_SYSTEM 0 - určeno pro systém #define IEVT_MSG_BROADCAST -1 - vysílání = určeno pro všechny speciální kódy odesílatele zprávy (pro IEVT_MESSAGE v poli from) : #define IEVT_MSG_EVENTSYS 0 - od IEvents knihovny makro pro testování TERMINATE zprávy : #define IEVT_TERM(e) ((e.what & IEVT_MESSAGE) && (e.x.msg.code == IEVT_MSG_TERMINATE)) priorita události : #define IEVT_ALERT INT_MIN - maximální priorita (v knihovně je to pouze zpráva TERMINATE) #define IEVT_NORMAL 0 - normální priorita Oblast ------ typedef struct { int x1; int y1; - levý horní roh int x2; int y2; - pravý dolní roh int id; - jedinečné ID oblasti (zadává uživatel) } IEVT_region; - oblast Jednotlivé události ------------------- struct IEVT_event_mouse { int x; - x-ová souřadnice myši int y; - y-ová souřadnice myši int b; - stav tlačítek myši (viz Allegro - mouse_b) int shifts; - stav klávesových přeřaďovačů (viz Allegro - key_shifts) int region; - ID aktuální oblasti nebo 0, je-li kurzor mimo jakoukoliv oblast nebo je kontrola oblasti vypnuta }; - IEVT_MOUSE_* události struct IEVT_event_key { int ascii; - ASCII kód klávesy (pouze při DOWN a REPEAT) int scancode; - scan kód klávesy (viz Allegro - key[]) int shifts; - stav klávesových přeřaďovačů (viz Allegro - key_shifts) }; - IEVT_KEY_* události struct IEVT_event_timer { unsigned long time; - čas od poslední IEVT_TIMER_TICK události }; - IEVT_TIMER_* události struct IEVT_event_message { int code; - kód zprávy int from; - kód odesílatele int to; - kód příjemce int data; - dodatečná data }; - IEVT_MESSAGE událost struct IEVT_event_user { int data[5]; - uživatelská data }; - IEVT_USER událost typedef struct { int what; - typ události int prior; - priorita (čím nižší tím větší) unsigned long when; - kdy byla uložena do fronty (měřeno v ms od IEVT_init) union { struct IEVT_event_mouse mouse; struct IEVT_event_key key; struct IEVT_event_timer timer; struct IEVT_event_message msg; struct IEVT_event_user user; } x; - data události int next; - interní informace } IEVT_event; - událost Globální proměnné ----------------- extern int IEVT_installed; - TRUE došlo-li k inicializaci extern int IEVT_use_parts; - povolení některých částí IEvents - bitová maska IEVT_USE_* konstant - nutno nastavit před voláním IEVT_init - std. IEVT_USE_ALL Globální funkce --------------- int IEVT_init (void); - inicializace - nebyly-li inicializovány některé části Allegra, učiní se tak - registruje IEVT_done pro spuštění při ukončení void IEVT_done (void); - ukončení práce knihovnou - voláno automaticky při skončení programu void IEVT_enable_events (int evtMask); - povolí dané události - jiné události než povolené neprojdou přes IEVT_post - std. jsou povoleny IEVT_DEFAULT void IEVT_disable_events (int evtMask); - zakáže dané události int IEVT_post (IEVT_event evt); - zařadí událost na konec fronty událostí (je-li povolena) - možno volat i z asynchronních fcí (interruptů) - vrací 0 při úspěchu, -1 při zaplnění fronty (nepodaří-li se uvolnit místo na základě priority) IEVT_event IEVT_peek_next (int evtMask); - vrací kopii první události ve frontě odpovídající masce - při neúspěchu vrací IEVT_NOTHING událost IEVT_event IEVT_get_next (int evtMask); - vrací první událost ve frontě odpovídající masce - tuto a všechny starší z fronty odstraní - při neúspěchu vrací IEVT_NOTHING událost a vymaže celou frontu void IEVT_flush (int evtMask); - vyřadí z fronty všechny události odpovídající masce IEVT_event IEVT_halt (int evtMask); - jako IEVT_get_next, ale funkce je ukončena až při úspěchu void IEVT_set_timer_tick (unsigned long interval); - nastaví časový odstup mezi jedn. IEVT_TIMER_TICK - údaj je v ms (std. 1000 ms = 1 s) unsigned long IEVT_get_timer_tick (void); - vrací hodnotu časového odstupu mezi jedn. IEVT_TIMER_TICK - viz. IEVT_set_timer_tick void IEVT_set_mouse_options (int clickTime, int clickRange, int dclickTime, int dragRange); - nastavuje různé volby pro myší události - clickTime : max. časový odstup mezi stiskem a puštěním tlačítka při kliknutí (v ms - std. 100 ms) - clickRange : max. odchylka (+/-) místa puštění tlačítka od místa stisku (std. 2 body) - dclickTime max. časový odstup mezi prvním a druhým klikem při dvojkliku (v ms - std. 250 ms) - dragRange min. odchylka (+/-) aktuálního místa od místa stisku při dragu (std. 2 body) void IEVT_get_mouse_options (int *clickTime, int *clickRange, int *dclickTime, int *dragRange); - vrací hodnoty různých voleb pro myší události - viz. IEVT_set_mouse_options void IEVT_terminate_msg (int enable); - TRUE povoluje zasílání TERMINATE zprávy - vyřazuje z provozu std. Allegro CTRL-ALT-DEL/END ošetření - po IEVT_done je vše vráceno do původního stavu void IEVT_send_terminate (void); - vyšle TERMINATE zprávu jako by vyšla z knihovny void IEVT_chord_middle (int enable); - TRUE povoluje emulaci prostředního tlačítka myši pomocí zbylých dvou - není zcela úplně funkční (spíše vůbec ne) unsigned long IEVT_read_timer (void); - vrací počet ms od IEVT_init - shodné s polem when v událostech void IEVT_priority (int enable); - TRUE povoluje zařazování událostí do fronty dle priorit (vyšší priorita jde dřív, v rámci stejných jde novější později) - std. nastavení je TRUE char * IEVT_dump_event (char *str, IEVT_event evt); - obsah události evt je převeden na čitelný řetězec, který je vrácen - str musí být alokován předem - vrací str void IEVT_regions (int enable); - TRUE povoluje kontrolu oblastí (std. ano) int IEVT_add_region (IEVT_region reg); - přidá oblast nad všechny ostatní - nekontroluje duplicitu ID - vrací 0 při úspěchu, -1 při zaplnění fronty int IEVT_remove_region (int id); - odstraní oblast dle ID - neodstraní oblasti s duplicitním ID - vrací 0 při úspěchu, -1 při nenalezení int IEVT_update_region (IEVT_region reg); - naplní oblast se stejným ID novými údaji - vrací 0 při úspěchu, -1 při nenalezení void IEVT_clear_regions (void); - smaže všechny oblasti int IEVT_active_region (void); - vrací číslo aktivní oblasti Šíření a spol. -------------- Viz. soubor license.txt.cz. Jakékoliv připomínky ohledně knihovny (chyby a zlepšení) mi napište! Neodpovídám za jakékoliv škody způsobené užitím této knihovny. Štěpán Roh