AmigaOS 3.5 - La nuova API della workbench.library

di Bernardo Innocenti <bernie@cosmos.it>

Abstract

Questo mese affronteremo un argomento che riguarda più da vicino i lettori che si occupano di programmazione. Infatti, moltissime novità introdotte nel Workbench V44 riguardano l'interfaccia con le applicazioni e rimarranno dunque inaccessibili agli utenti finché non saranno disponibili applicazioni che ne traggono vantaggio. 

Apertura di oggetti

Grazie a OpenWorkbenchObject(), le applicazioni possono ora lanciare programmi in modo Workbench, in pratica simulando il doppio click su di un'icona. Questa caratteristica è estremamente utile per i cosiddetti tool launcher, come ToolManager o ToolsDaemon, che finora utilizzavano tecniche di programmazione non ufficiali per ottenere una funzionalità equivalente.  estende e rende obsolete le funzionalità offerte dal WBStart-Handler e dalla wbstart.library. Di quest’ultima è disponibile una versione aggiornata per l’OS 3.5 (la trovate sul CD allegato alla rivista). Purtroppo OpenWorkbenchObject() non può essere utilizzata fino a che il Workbench non viene caricato.

Questo esempio estratto dall'AutoDoc di OpenWorkbenchObject() mostra come è 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() è anche possibile aprire finestre del Workbench:

OpenWorkbenchObjectA("SYS:Prefs", NULL);

La medesima funzionalità è disponibile anche dalla porta ARexx del Workbench impartendo il comando:

ADDRESS 'WORKBENCH' WINDOW 'SYS:Prefs' OPEN

L'esecuzione di programmi in modo Workbench da parte di uno script ARexx può 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

Più controllo sul Workbench

WorkbenchControl() viene incontro alle esigenze di tutte quelle applicazioni che interagiscono con il Workbench per estenderne le funzionalità. In precedenza, molte delle informazioni e delle funzionalità messe a disposizione da questa funzione dovevano essere ottenute utilizzando tecniche di programmazione tutt’altro che lecite (difatti, alcuni di questi trucchetti sono divenuti inefficaci già in questa versione).

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). Questi tag, l'uso dei quali è sconsigliabile nelle normali applicazioni, sono descritti in dettaglio nel riquadro 2.

AppIcons 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 AppIcons 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. Quando l’utente seleziona uno di essi, il Workbench invia un AppMessage con il campo am_Class impostato ad uno dei valori AMCLASSICON_XXX, in modo che l’applicazione  possa reagire in modo appropriato.

Nel caso che l’applicazione fosse interessata a tenere traccia della posizione della propria AppIcon, può impostare a TRUE il tag WBAPPICONA_PropagatePosition. In questo modo il Workbench aggiornerà i campi do_CurrentX e do_CurrentY della struttura DiskObject dalla quale è stata creata la vostra AppIcon. Oltre alla posizione è possibile essere informati sullo stato di selezione di un’AppIcon (click singolo). Se viene impostando il tag booleano WBAPPICONA_NotifySelectState, il Workbench genera un AppMessage di tipo AMCLASSICON_Selected ogni volta che l’icona viene selezionata ed uno di tipo AMCLASSICON_Unselecte quando torna ad essere deselezionata.

È inoltre possibile creare icone con immagini animate o generate dinamicamente. Il tag WBAPPICONA_RenderHook specifica una funzione utente che verrà chiamata in luogo delle normali routine di disegno impiegate dal Workbench. In questo modo si possono creare icone a più 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 versatilità delle AppIcon del nuovo Workbench. (nel momento in cui scriviamo, AnimatedIcon non è 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, è possibile definire aree rettangolari all'interno delle finestre in cui è consentito il drop (rilascio) delle icone utilizzando la nuova funzione AddAppWindowDropZone(). Il programma IconEdit del Workbench 3.5 è un esempio di applicazione che utilizza questa nuova caratteristica. È possibile rilasciare icone sia sull'area di disegno che su ciascuna delle due immagini (normale e selezionata), ottenendo così 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 comodità della quale avremmo potuto fare a meno senza troppi rimpianti. In realtà le Drop Zones offrono una interessante possibilità che finora nessuna applicazione, IconEdit incluso, ha messo a frutto. Se di receente avete avuto occasione di usare un desktop MacOS, Motif o Windows, avrete senza dubbio notato come le operazioni di drag (trascinamento) siano accompagnate da un'indicazione visiva dell'operazione che si può 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() è 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 può essere utilizzata per evidenziare l'area attiva disegnando nella finestra. Ci auguriamo di vedere presto applicazioni che si avvalgono di questa caratteristica.

Non è tutto

Per questa volta vi abbiamo dato solo un piccolo assaggio delle novità 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 è tiranno, ma ci ripromettiamo di approfondire gli argomenti rimasti nei prossimi mesi.

RIQUADRO 1: I tag ufficiali di WorkbenchControl()

WBCTRLA_IsOpen
   Ritorna TRUE se la finestra speficata è 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
Richiede al Workbench di ridisegnare l'immagine di una AppIcon. Questo tag può 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 può 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 è accessibile anche con l'editor di preferenze Workbench, dal quale non è 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 ambiguità 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 è 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 è la rilettura completa delle directory ad ogni cambiamento, pertanto questa funzione è 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_PropagatePosition (aggiorna la posizione dell’icona)
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 è 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.

NOTE PER L’IMPAGINATORE:

Il testo in Courier deve rimanere ben distinto dal resto del testo. Trattandosi di codice sorgente, è importante che la formattazione rimanga invariata (compresa la punteggiatura). Nel caso sia necessario usare un font diverso, ne raccomando comunque uno a spaziatura fissa. Possibilmente le righe non devono essere interrotte (né tantomeno sillabate!).