ButClk
                                  ======


Button Clock is a typical QL clock job. This one is designed to reside in
the QPac2 Button Frame.

 


Note: This is a silly little program, although I quite like it, myself.
It uses way too many resources for what it does. There are plenty of
alternatives out there that do pretty much the same at less than half the
cost! It is designed for SMSQ/E, although you can squeeze it into
Qdos/Minerva if you have an abundance of memory and anyway use the many
extra systems extensions it requires. Look at it more as a POC rather than
an ideal utility!


Requirements
============

SMSQ/E (or Qdos/Minerva with TK2 V2.3+ *, ptrgen, Wman2 and probably the
Hotkey system too. Also Homedir_bin). It also requires Qpac2's Button Frame,
QLIB_run (or equivalent), and EasyPointer's ptrmen_cde.

The program requires CLK_obj to reside in ButClk's Home Directory.

Clearly, the program is made for systems where these "extras" are
considered a matter of course. There are plenty of other clocks out there
that dont need any of this!

*) TK2 V 2.30 for the QL/Minerva added the EX_M command; however it also
removed the CLOCK command due to lack of space. So if you use TK2 up to
V2.13, you need to alter ButClk's EX_M command to EX (no big deal,
really) and recompile. If you use TK2 V2.3+ you will need to load the
CLOCK_cde toolkit (see below). You could, if you like, compile this in
with the CLK program - or just LRESPR it separately for use system wide.


The ButClk utility consists of the following components:

ButClk_obj      - this is the main executable, the program you launch at
                  some time in your boot sequence.
ButClk_bas      - this is the S*BASIC source code for the above
ButClk_txt      - this document
ButClk_cde      - a toolkit required to recompile ButClk_bas.
                  Not needed for normal operation of the compiled program
ButClk_asm      - the ButClk-specific source code for the above toolkit
                  (the remaining code can be found in the toolkit section
                  of Knoware.no)
ButClk_link     - the Qmake linker file for the above

CLK_obj         - this is a secondary program to display the detailed time
                  and date. It acts as a hint popup to ButClk. It must
                  reside in the same directory as ButClk_obj
CLK_bas         - the S*BASIC source code for the above
CLK_CDE         - the toolkit commands needed by CLK_bas, compiled in with
                  the CLK_obj program
CLK_asm           the CLK-specific source code for the above
PEHEAD_asm      - bridging code to handle the PE component(s) for the above
CLK_men         - the menu definition for CLK
CLK_men_rel     - the above in SROFF format for inclusion in the CLK
                  toolkit

CLOCK_cde       - not included here. Needed for Qdos/Minerva systems using
                  TK2 V2.30 or above. Can be found at Knoware.no under
                  toolkits/compatibility

Use
===

ButClk cant be invoked with the usual BT_xxx commands, as the job has
special requirements of the button window. Simply EX ButClk_obj at the
point in your boot program (for example) when you want the program to
appear in the Button Frame.

The job takes a single, optional, prameter: exactly one digit between 0
and 3, representing the system palette number you require. If none - or a
nonsensical value - is given, the palette reverts to 0.

HITing the button opens a Hint window with a more detailed date and time
display. Any keystroke or movement of the pointer terminates the detailed
display.

Pressing ESC while the pointer is in the button window terminates the job.

The CLK program CAN be executed as a separate job, but it is intended to
be invoked by ButClk. Details of parameters and use can, if required, be
found in its S*BASIC source code.


Program notes
=============

Why go to all this trouble for a button clock?! Well, I needed a new one
and I didnt particularly like any of the others on offer. And being a
QLer, of course I had to make my own!

However, it isnt all about fun and frivolity. There are a few things of
note that MAY be found useful in other, more serious, contexts.

First of all the is all the button stuff. This is explored more precisely
in my Button toolkit, found here.

Secondly, there is the external popup routine; one program calling up
another to avoid the PE limitations of a job's display being confined to
the outline of the main program. This is explored in more detail in my
Poxology article and associated programs at Articles.

Thirdly, there is the feature of one job outputting its display through
the screen channel of another job. This only really works for simple text
(not graphics) where the update frequency is slow and not required to be
entirely regular. This is a feature of Tony Tebby's CLOCK command/program.
The issue was discussed on QL forum some time ago under the topic
"Passing channels to jobs". See the thread here for more information.


Program status
==============

The source code for the included toolkits can be found in my pick 'n' mix
toolkit on Knoware.no

V0.01, pjw, 2021 Apr 19
V0.02, pjw, 2021 May 30, Click instead of hover for detailed display
V0.02, pjw, 2022 Oct 05, programs moved to a different location. Source
                         files adjusted to reflect that and reassembled &
                         recompiled

               Conditions of use and DISCLAIMER as per Knoware.no

Generated by QuickHTM, 2022 Oct 13