LABTITLE=: 'Taskbar Notification Area'
LABFOCUS=: 1

NB. =========================================================
Lab Section Introduction
The Notification Area is the portion of the Windows taskbar
on the right near the clock.  Long-running applications
which do not require a presence on the desktop, but require
occasional user interaction, will put an icon in this area
to let the user to call it when required.

An example is a mouse driver which puts an icon in this
area to allow the user to change settings.

Another is an email program which puts an icon there when
there are unread messages.
)
PREPARE
3 : 0''
if. IFJAVA >: IFWIN32 do.
  a=. 'The Taskbar Notification Area lab will only work in the Windows system (Jwdw).'
  wdinfo 'Taskbar Lab';a
end.
)
PREPARE

NB. =========================================================
Lab Section
The script '~system\classes\winapi\notify.ijs' defines a
class which allows you to create, modify, and remove an icon
from the taskbar.
)
load '~system\classes\winapi\notify.ijs'

NB. =========================================================
Lab Section
Once an icon is created, mouse movements and clicks over it
will cause a message to be sent to J.  Similar to window
driver events, this causes a J expression to be run, eg:

   wdmsg_handler 32768 0 513

This means that message 32768 has been sent to J.  32768
(WM_APP) is the application-defined message used by
jnotify.

The other two numbers represent the ID of the icon (0),
which is specified by the J code using jnotify, and
the event 513 (WM_LBUTTONDOWN), meaning the left mouse
button has been clicked over the icon.

The standard wdmsg_handler verb will cause a call to the
<notify_handler> verb in the locale which created the
jnotify instance, with the same argument.
)

NB. =========================================================
Lab Section
By creating an instance of a jnotify class, and writing a
<notify_handler> verb to respond to events in it, a J
application can interact with the user via this icon in the
taskbar.

The following steps through a simple example.
)

NB. =========================================================
Lab Section
We start by creating the icon.  The argument to conew
has the following elements:

  - filename containing the icon.  In this case we use the
    J executable which contains the familiar J icon.
  - icon index.  In this case 0, meaning the first icon
    defined in the executable file.
  - tooltip.  The text which is displayed when the mouse
    hovers over the icon.
  - ID.  This is the number included in the right argument
    to the <wdmsg_handler> call.  This lets an application
    define several icons and distinguish amongst them in
    the handler verb.

After execution of the following line you should see a J
icon in your taskbar notification area.
)
n=: ((jpath '~home\j.exe');0;'J Tooltip';42) conew 'jnotify'

NB. =========================================================
Lab Section
Moving or clicking your mouse over the icon will cause
value errors in J as the handler verb has not yet been
defined.

It is safe to continue with this lab after any errors
created by mouse activity over the taskbar icon.
)

NB. =========================================================
Lab Section
We now define a simple handler verb to respond to events on
the icon.  The verb ignores everything but a left mouse
button click, and responds to it with a message box.
)
notify_handler=: verb define
'wm wparam lparam'=. y.
select. lparam
  case. WM_LBUTTONDOWN_jnotify_ do.
    wd 'mb Testing *Left mouse button clicked.'
end.
empty ''
)

NB. =========================================================
Lab Section
Clicking on the left mouse button on the icon will now
result in a message box.
)

NB. =========================================================
Lab Section
We can now modify the icon, as an application might do to
inform the user of some change in state.

In this case, we change the icon to the red J icon.

The behavior of the icon does not change.
)
modify__n (jpath '~home/jr.ico');0;'J Tooltip';42

NB. =========================================================
Lab Section
The icon is deleted by destroying the instance.
)
destroy__n ''

NB. =========================================================
Lab Section
The "J Viewer" sample application shows what can be done
with the jnotify class.

It puts an icon in the notification area, and responds to
mouse clicks as follows.

Left clicks offer a selection of how J should process data
in the clipboard:
  - "Hex dump" treats the clipboard as a file name, and
    displays a hexadecimal dump of the contents of the file.
  - "Plot" treats the clipboard as numbers, and display a
    plot window representing those numbers.  It works with
    either a single line of numbers, or a table of numbers.
  - "Browse" treats the clipboard as a fragment of HTML, and
    starts a browser displaying those contents.

Right clicks allow the user to close the application, display
the J session, or display the traditional "about" box.

The next steps starts the sample application and exercises
it.
)

NB. =========================================================
Lab Section
We start the application as a separate instance of J.

The icon in the taskbar is a J with a magnifying glass
over it.

Note that the command line starting the application includes
the  -jijx  option, which causes J to start the application
without displaying an IJX window.
)
j=: jpath '~home\j.exe'
wd 'winexec *',j,' -jijx ~system\examples\winapi\viewer.ijs'

NB. =========================================================
Lab Section
Try the right click menu first:  Close, About, and Show.
"Show" displays the J execution window, and the selection
changes to "Hide" to remove it from the desktop.

If you close the application, restart it by executing the
winexec line above before proceeding.
)

NB. =========================================================
Lab Section
Now we try the left-click menu.

"Hex dump" reads a file and formats it as hexadecimal.

The following puts a file name in the clipboard.  Left-click
the J icon and select "Hex dump".
)
]f=: jpath '~home/jr.ico'
wd 'clipcopy *',f  NB. put filename into clipboard

NB. =========================================================
Lab Section
Files can also be copied directly from a Windows explorer
window.

Try copying a couple files from an Explorer window, then
Left-click the J icon and select "Hex dump".
)

NB. =========================================================
Lab Section
"Plot" displays a plot of numbers.

The following puts a list of numbers in the clipboard.
Left-click the J icon and select "Plot".
)
load 'trig numeric'
n=: ":sin steps 0 4p1 50
(55{.n),'...'

wd 'clipcopy *',n

NB. =========================================================
Lab Section
Using "Plot" again, but with a table of numbers:
)
]n=: */~ i. 15   NB. multiplication table

load 'format'  NB. for <flatten>
wd 'clipcopy *',flatten n

NB. =========================================================
Lab Section
"Browse" displays an HTML fragment in a browser window.

The following puts some HTML in the clipboard.  Left-click
the J icon and select "Browse".
)
h=: '<P>This is some <FONT color="Red">red</FONT> text.</P>'
wd 'clipcopy *',h

NB. =========================================================
Lab Section
Another sample application using the notification area is
in the script '~system\examples\winapi\hidesess.ijs'.

It defines <smhidesession> and <smshowsession>, both in the
jijs locale.  Hiding a session causes all forms to be hidden,
and a J icon is placed in the taskbar.  Clicking the icon
shows all the windows again.

Load the script:
)
load '~system\examples\winapi\hidesess.ijs'

NB. =========================================================
Lab Section
The next step opens the project manager, debugger, and a
find-in-files window.
)

NB. =========================================================
Lab Section
)
jijs_runprojman_button_jijs_ ''
jijs_rundebug_button_jijs_ ''
jijs_editfif_button_jijs_ ''

NB. =========================================================
Lab Section
The next step will execute:

   smhidesession_jijs_ ''

To restore the session, click on the new J icon in the
taskbar.
)

NB. =========================================================
Lab Section
Hiding the session:
)
smhidesession_jijs_ ''

NB. =========================================================
Lab Section
You should also close the viewer sample application if it
is still running.
)
