AmigaOS 3.5 - La nuova API della workbench.library ================================================== di Bernardo Innocenti Abstract -------- Questo mese affronteremo un argomento che rigurarda piu' da vicino i lettori che si occupano di programmazione. La maggior parte delle novita' introdotte nel Workbench V44 riguardano infatti l'interfaccia con le applicazioni e rimarranno dunque inaccessibili agli utenti finche' non saranno disponibili applicazioni che ne traggono vantaggio. OpenWorkbenchObject() --------------------- Le applicazioni possono ora lanciare programmi in "modo Workbench", simulando cioe' il doppio click su di un'icona. Questa caratteristica e' estremamente utile per i "tool launcher" come ToolManager o ToolsDaemon, che fin'ora utilizzavano tecniche di programmazione non ufficiali per ottenere una funzionalita' equivalente. Questo esempio estratto dall'AutoDoc di OpenWorkbenchObject() mostra come e' possibile lanciare Multiview per visualizzare la Startup-Sequence: success = OpenWorkbenchObject("MultiView", WBOPENA_ArgLock, Lock("S:", SHARED_LOCK), WBOPENA_ArgName, "Startup-Sequence", TAG_DONE); La funzione costruisce un messaggio WBStartup con associata una lista di argomenti (WBArg) da passare all'applicazione. Utilizzando OpenWorkbenchObject() e' anche possibile aprire finestre del Workbench: OpenWorkbenchObjectA("SYS:Prefs", NULL); La medesima funzionalita' e' disponibile tramite la porta ARexx del Workbench tramite il comando: ADDRESS 'WORKBENCH' WINDOW 'SYS:Prefs' OPEN L'esecuzione di programmi in modo Workbench da parte di uno script ARexx puo' invece avvenire soltanto dopo aver aperto la finestra che ne contiene l'icona: ADDRESS 'WORKBENCH' WINDOW 'SYS:Utilities' OPEN ICON WINDOW 'SYS:Utilities' NAMES 'Clock' OPEN WorkbenchControl() ------------------ WorkbenchControl() viene incontro alle esigenze di tutte quelle applicazioni che interagiscono con il Workbench per estenderne le funzionalita'. In precedenza, molte delle informazioni e delle funzionalita' messe a disposizione da WorkbenchControl() dovevano essere ottenute utilizzando tecniche di programmazione tuttaltro che lecite. Difatti, alcuni di questi articifi sono divenuti inefficaci gia' in questa versione del Workbench. WorkbenchControl() accetta in input una lista di tag che sono descritti nel riquadro 1. Esistono inoltre dei tag non documentati negli AutoDocs che possono essere utilizzati da applicazioni come TweakWB (presente sul CD allegato alla rivista). Questi tag, l'uso dei quali e' sconsigliabile nelle normali applicazioni, sono descritti in dettaglio nel riquadro 2. AppIcon intelligenti -------------------- Fino al Workbench 3.1 l'interazione con le AppIcon (le icone create dalle applicazioni sulla finestra principale del Workbench) poteva avvenire solamente effettuando un doppio click o rilasciando icone su di esse. Per alcune applicazioni era sentita l'esigenza di manipolare le AppIcon come se fossero delle normali icone. Il nuovo Workbench permette finalmente alle applicazioni di rispondere in modo congruente a tutte le operazioni che si possono effettuare sulle icone. I nuovi tag booleani WBAPPICONA_SupportsXXX (elencati nel riquadro 3) possono essere passati ad AddAppIcon() per attivare selettivamente ciascuno di questi comandi. E' inoltre possibile creare icone con immagini animate o generate dinamicamente. Il tag WBAPPICONA_RenderHook specifica una funzione dell'utente che verra' chiamata in luogo delle normali routine di disegno impiegate dal Workbench. In questo modo si possono creare icone a piu' stati (come il cestino del Macintosh), o con funzioni informative (come l'IconClock del Directory Opus). Recentemente gli sviluppatori di AmigaOS 3.5 hanno realizzato l'utility AnimatedIcon a dimostrazione della versatilita' delle AppIcon del nuovo Workbench. (nel momento in cui scriviamo, AnimatedIcon non e' ancora disponibile pubblicamente). Drop Zones ---------- A partire dal Workbench V36 (2.0), le applicazioni possono abilitare il drag&drop delle icone sulle proprie finestre utilizzando la funzione AddAppWindow(). A partire dal Workbench V44, e' possibile definire delle aree rettangolari all'interno delle finestre in cui e' consentito il /drop/ (rilascio) delle icone utilizzando la nuova funzione AddAppWindowDropZone(). Il programma IconEdit del Workbench 3.5 e' un esempio di applicazione che utilizza questa nuova caratteristica. E' possibile infatti rilasciare icone sia sull'area di disegno che su ciascuna delle due immagini (normale e selezionata), ottenendo cosi' la sostituzione di una sola delle due immagini. In precedenza era possibile emulare un simile comportamento scrivendosi del codice che tiene conto delle coordinate del mouse al momento del rilascio dell'icona (esse sono disponibili nella nei campi am_MouseX e am_MouseY della struttura AppMessage). Le Drop Zones sembrano dunque una comodita' della quale avremmo potuto fare a meno senza troppi rimpianti. In realta' le Drop Zones offrono una interessante possibilita' che finora nessuna applicazione, IconEdit incluso, ha messo a frutto. Se di receente avete avuto occasione di usare un desktop MacOS, X11/Motif o Windows, avrete senza dubbio notato come le operazioni di drag (trascinamento) siano accompagnate da un'indicazione visiva dell'operazione che si puo' compiere rilasciando l'icona in una certa posizione. Il puntatore o l'area interessata si "attivano" al passaggio del mouse per offrire una forma di feedback visivo all'utente. Ebbene, con AddAppWindowDropZone() e' possibile fare in modo che una funzione callback dell'applicazione venga richiamata ogni qual volta il mouse entra o esce da una drop zone. Questa funzione puo' essere utilizzata per evidenziare l'area attiva disegnando nella finestra. Ci auguriamo di vedere presto applicazioni che si avvalgono di questa caratteristica. Non e' tutto ------------ Questa volta vi abbiamo dato solo un piccolo assaggio delle novita' che stanno "sotto la scorza" dell'OS 3.5, la maggior parte delle quali devono ancora essere portate alla luce da nuove applicazioni che ci auguriamo di vedere presto. Lo spazio come sempre ci e' tiranno, ma ci ripromettiamo di approfondire gli argomenti rimasti nei prossimi mesi. WBAPPICONA_NotifySelectState RIQUADRO 1: I tag ufficiali di WorkbenchControl() WBCTRLA_IsOpen Ritorna TRUE se la finestra speficata e' aperta. WBCTRLA_DuplicateSearchPath WBCTRLA_FreeSearchPath Il primo tag permette di ottenere una copia del path utilizzato dal Workbench per cercare le applicazioni da eseguire. Il secondo tag rilascia la memoria allocata per il path. WBCTRLA_SetDefaultStackSize WBCTRLA_GetDefaultStackSize Ritorna o imposta la dimensione dello stack utilizzato dal Workbench per lanciare i programmi un modo shell. WBCTRLA_RedrawAppIcon Righiede al Workbench di ridisegnare l'immagine di una AppIcon. Questo tag puo' essere impiegato per simulare icone animate. WBCTRLA_GetProgramList WBCTRLA_FreeProgramList Il primo tag permette di ottenere una lista dei programmi lanciati in modo Workbench che sono attualmente in esecuzione. Questa lista puo' essere utilizzata per tentare di chiudere ognuno di essi automaticamente prima di uscire da Workbench. Il secondo tag permette di liberare la memoria allocata. WBCTRLA_GetSelectedIconList WBCTRLA_FreeSelectedIconList Ritorna una lista contenente il path completo delle icone attualmente selezionate (ad eccezione delle AppIcons). Questa feature permette di realizzare programmi che eseguono operazioni sulle icone selezionate richiamando un comando dal menu Tools (Strumenti) del Workbench o clickando su un bottone di una toolbar. WBCTRLA_GetOpenDrawerList WBCTRLA_FreeOpenDrawerList Ritorna una lista contenente il path completo dei cassetti aperti nel Workbench. WBCTRLA_AddHiddenDeviceName WBCTRLA_RemoveHiddenDeviceName WBCTRLA_GetHiddenDeviceList WBCTRLA_FreeHiddenDeviceList Questi tag permettono di manipolare la lista dei volumi e device che non devono essere mostrati dal Workbench. Questa caratteristica e' accessibile anche con l'editor di preferenze Workbench, dal quale non e' tuttavia possibile specificare nomi di device che non sono attualmente montati. WBCTRLA_GetTypeRestartTime WBCTRLA_SetTypeRestartTime Questi tag permettono di leggere ed impostare l'intervallo di tempo durante il quale il Workbench permette di digitare da tastiera una parte del nome di un'icona per poterla selezionare in caso di ambiguita' sul primo carattere. RIQUADRO 2: I tag non documentati di WorkbenchControl() WBCTRLA_GetMaxCopyMem WBCTRLA_SetMaxCopyMem Questi tag permettono di leggere ed impostare il limite massimo di memoria utilizzata dal Workbench durante la copia dei file. WBCTRLA_GetImageMemType WBCTRLA_SetImageMemType Legge/imposta gli attributi utilizzati dal Workbench per allocare memoria per le immagini. Il default e' MEMF_CHIP, ma i sistemi RTG consentono generalmente di utilizzare memoria di tipo MEMF_FAST. WBCTRLA_GetDrawerNotification WBCTRLA_SetDrawerNotification Questi tag controllano la notifica sulla modifica dei file visualizzati nei cassetti aperti in modo "Mostra tutti i file". Purtroppo l'effetto che si ottiene e' la rilettura completa delle directory ad ogni cambiamento, pertanto questa funzione e' stata disabilitata per default. WBCTRLA_SetGaugeEnabled WBCTRLA_GetGaugeEnabled Legge/imposta lo stato di attivazione dell'indicatore di riempimento che compare a sinistra delle finestre principali dei volumi. RIQUADRO 3: Nuovi tag di AddAppIcon() WBAPPICONA_SupportsOpen (Apri) WBAPPICONA_SupportsCopy (Copia) WBAPPICONA_SupportsRename (Rinomina...) WBAPPICONA_SupportsInformation (Informazioni...) WBAPPICONA_SupportsSnapshot (Fissa) WBAPPICONA_SupportsUnSnapshot (Annulla Fissaggio) WBAPPICONA_SupportsLeaveOut (Estrai) WBAPPICONA_SupportsPutAway (Reinserisci) WBAPPICONA_SupportsDelete (Cancella) WBAPPICONA_SupportsFormatDisk (Formatta Disco) WBAPPICONA_SupportsEmptyTrash (Svuota Cestino) WBAPPICONA_RenderHook (funzione di disegno custom) RIQUADRO 4: Esempio di uso delle Drop Zones #define ZONA_SUPERIORE 1 #define ZONA_INFERIORE 2 /* ...chiama OpenWindow()... */ /* ...chiama AddAppWindow()... */ dz_sup = AddAppWindowDropZone(appWindow, ZONA_SUPERIORE, 0, WBDZA_Left, 10, WBDZA_Top, 10, WBDZA_Width, 200, WBDZA_Height, 90, TAG_DONE); dz_inf = AddAppWindowDropZone(appWindow, ZONA_INFERIORE, 0, WBDZA_Left, 10, WBDZA_Top, 100, WBDZA_Width, 200, WBDZA_Height, 90, TAG_DONE); RIQUADRO 5: sommario delle nuove funzioni successo = OpenWorkbenchObjectA(nomeFile, tags) Apre un cassetto o lancia un programma come se l'utente avesse effettuato un doppio click sulla sua icona. successo = CloseWorkbenchObjectA(nomeFile, tags) Chiude un cassetto del Workbench come se l'utente avesse clickato sul gadget di chiusura della finestra. successo = WorkbenchControlA(nomeFile, tags) Richiede o modifica i parametri globali del Workbench. dropzone = AddAppWindowDropZoneA(appWindow, id, userData, tags) Imposta un'area di una AppWindow in cui e' ammesso il rilascio (drop) delle icone. successo = RemoveAppWindowDropZone(appWindow, dropZone) Tenta di rimuovere una drop zone dalla AppWindow specificata. successo = ChangeWorkbenchSelectionA(nomeCassetto, hook, tags) Cambia lo stato di selezione delle icone contenute in una finestra del Workbench invocando una funzione dell'utente su ognuna di esse. successo = MakeWorkbenchObjectVisibleA(nomeIcona, tags) Cambia le dimensioni di una finestra del Workbench in modo da rendere visibile una particolare icona.