Program:  Superbase
Version:  2.0
Date:     February 12, 1993
Topic:    Setting the state of an icon button

Summary:  Setting the state of a particular icon button
using the ICON command in SBL lets you control whether an
icon is displayed as Selected,  Enabled, or Disabled.
However, when an icon bar button is attached to an internal
procedure, the state of the button becomes the
responsibility of Superbase and cannot be set or controlled
by the programmer.  Also, once an ICON command is issued to
change the state of an icon bar button, it is only necessary
to issue an ICON ON command to refresh the icon bar.  Use of
the ICON UPDATE command for this purpose would cause
unnecessary screen flicker.  By reviewing the following
steps, you learn how to setup an icon bar in the Icon Bar
Editor and how to change the state of an icon button using
SBL.

Setup an icon bar

1.   In Superbase, choose the File/Modify/Icon Bar menu item
     to bring up the Icon Bar Editor.  Maximize the Icon Bar
     Editor window to avoid confusion between the Icon Bar
     Editor menus and the Superbase menus.

2.   Choose the File/Get Default menu item to bring up the
     default Superbase icon bar.

3.   Now double-click the "+" icon button to bring up the
     Icon Bar Item Properties dialog box.

4.   Click the checkbox marked Selected then click the Set
     button.  Notice how the "+" icon button on the icon bar
     appears as if it is selected.

5.   Now click the checkbox marked Unavailable then click
     the Set button.  Notice how the "+" icon button becomes
     disabled.  The Unavailable checkbox has precedence over
     the Selected checkbox when both are checked.

6.   Click the checkbox marked Selected so that it is not
     checked, then click the Set button.  Notice how the "+"
     icon button still appears as if it is disabled.

7.   Choose the File/Use as current menu item to set this as
     the current Icon Bar for Superbase.

8.   Choose the File/ Exit menu item to exit the Icon Bar
     Editor.  When the dialog box asks if you want to "Save
     changed icon bar" click No.

9.   In Superbase, open the ORDER file in the STOCK
     subdirectory under SAMPLES or open any other data file.
     Notice how the "+" icon button is not disabled even
     though you set it as Unavailable in the Icon Bar
     Editor.  The reason for this is because the procedure
     associated with the "+" icon button, AddItem( ), is an
     internal Superbase procedure and therefore, Superbase
     solely controls the state of the button.  If you write
     your own procedure and name it the same as one of the
     internal Superbase procedures, your procedure will have
     precedence, but its state is still controlled by
     Superbase.

Changing the state of an icon bar button

The following code gives an example of how to change the
state of an icon bar button which calls a user-defined
procedure.  Before running this code, make sure a Superbase
file is open.

REM Superbase V2.0 Icon Bar Demo Program
SUB main()'                         SBL Program starts here
      CALL ICONBAR()'  Call procedure to define new ICON BAR
      ICON UPDATE '    Displays the newly defined ICON BAR
      ICON ON '        Makes ICON BAR active and sets the
states
      REM SET ICON FROM CURRENT   --   Can be used to set as
the current Superbase
      REM                              ICON BAR
     CLEAR ERRNO '       Clear the ERRNO system variable
     SET ERROR OFF 11'   Disable error checking for Error 11
     REM loops until STOP or <CTRL> <Break>
     WHILE ERRNO <> 11
           WAIT ICON '   Waits for user to click on ICON BAR
     WEND
END SUB

SUB ICONBAR()'          Procedure to define ICON BAR
      ICON CLEAR'       Clear any icon bar defined in memory
      ICON 1, FILE '                          File List Box
      ICON 2, INDEX '                  Index List Box
      ICON 3,"TableView","TableView"'    Table view icon
      ICON 4,"PageView","PageView"'      Page view icon
      ICON 6,"TextTool","OutMessage"'    "abc" icon button
with Default State (Enabled)
END SUB

SUB OutMessage()'   Procedure outputs a message and toggles
the icon button
      ICON 6,"TextTool","OutMessage",2' Set "abc" icon
button as Selected
      REM ICON UPDATE'             Command would cause
screen flicker
      ICON ON '                    Displays the state change
with no flicker
      REQUEST "Notice how the 'abc' Icon Button","appears as
if it is Selected",0
      ICON 6,"TextTool","OutMessage",1' Set "abc" icon
button as Enabled
      ICON ON '                    Displays the state change
with no flicker
END SUB

     Notice that in the OutMessage() procedure, the ICON
UPDATE command was not used to display the state change of
our icon button.  The use of the ICON UPDATE command in this
case would have caused unnecessary screen flicker.  The ICON
UPDATE command must be used if you want to change the icon
or the procedure which goes with the icon button.

The program does not use the SET ICON FROM CURRENT command
because you want the default Superbase icon bar to appear
when the SBL program ends.  If the SET ICON FROM CURRENT
command is used, the icon bar set up by the ICONBAR()
procedure would remain as the current Superbase icon bar.
Since the SET ICON FROM CURRENT command causes the whole
icon bar to be re-drawn, it should only be used when
functionally necessary.