AmigaOS 3.5 - La nuova API della workbench.library
==================================================

di Bernardo Innocenti <bernie@cosmos.it>


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.
