/******************************************************************************
 * This program is subject to copyright protection in accordance with the
 * applicable law and is also subject to the Developer Download Software
 * License Agreement, ("License Agreement") agreed to by the licensee prior to
 * download and receipt of this program.  It must only be used for the purpose
 * of developing software that is compatible with the CLI handheld computer.
 * It must not, except as permitted in the License Agreement, by any means or
 * in any form be reproduced, distributed or lent.  Moreover, no part of the
 * program may be used, viewed, printed, disassembled or otherwise interfered
 * with in any form, except where allowed by the License Agreement, without the
 * express written consent of the copyright holder.
 *
 * THIS PROGRAM IS FURTHER PROVIDED "AS IS" WITH NO WARRANTY OF ANY KIND AND
 * THE COPYRIGHT HOLDER HEREBY DISCLAIMS ALL WARRANTIES, EXPRESS AND IMPLIED AS
 * TO THE PROGRAM.
 *
 * Copyright (c) 2002-2003 Sony Electronics Inc.
 * Some portions copyright (c) 1999 Palm Computing, Inc. or its subsidiaries.
 * All Rights Reserved.
 *
 * File: README.txt
 *
 *****************************************************************************/


SilkSample -- sample code to demonstrate basic usage of the Sony Silk
                library and workarounds to common problems


History:
    2003-07-31  added support for horizontal silkscreen resizing

    2002-11-08  added support for CLIE handhelds running Palm OS 5;
                first public version

    2002-04-08  initial version


Files:
    SilkSample.h    -- common header file
    SilkSample.cpp  -- common application code
    MainForm.cpp    -- code specific to the main Form;
                       MainForm supports resizing the virtual silkscreen
                         area and demonstrates how to reposition Form
                         objects appropriately
    SecondForm.cpp  -- code specific to the second Form;
                       SecondForm supports resizing the virtual silkscreen
                         area and demonstrates how to handle custom drawing
                         appropriately
    ThirdForm.cpp   -- code specific to the third Form;
                       ThirdForm does not support resizing the virtual
                         silkscreen area and demonstrates how to
                         enable/disable silkscreen resizing for specific
                         Forms

    SilkSampleRsc.h -- resource ID number definitions
    SilkSample.rsrc -- Constructor resource file


Overview:
    (See the "Virtual Silkscreen: Sony Silk Library" chapter in the
    "Programmer's Companion for Sony CLI Handheld" document for more
    information about the Sony Silk API.)

    1. On startup: load the Sony Silk library, open it, and register for
       sysNotifyDisplayChangeEvent notifications.
    2. When a Form is opened, enable or disable silkcreen resizing as
       desired and position widgets.
    3. When the silkscreen area is resized, resize the desired Form by
       calling WinSetBounds() and reposition its widgets.

       NOTE: The active Form or window may not be the Form you wish to
             resize if a dialog box or alert is displayed.  If the Form
             you wish to resize is not currently active, the notification
             handler should defer drawing operations to when the Form
             regains focus. (See notes below.)
    4. On exit: restore the silkscreen state, unregister for the
       sysNotifyDisplayChangeEvent notifications, disable silkscreen
       resizing, and close the Sony Silk library.


Notes:
    When handling resizing of the virtual silkscreen area, applications
    MUST be careful not to perform any drawing operations in the
    sysNotifyDisplayChangeEvent notification handler if a dialog box or
    alert is active.

    To avoid this problem, the SilkSample project checks the active Window
    in its notification handler.  When the virtual silkscreen area is
    resized, the handler first checks if the current Window belongs to the
    intended Form.  If it does not, a flag is set so that the intended Form
    can update itself properly on the next winEnter event.

    Note that merely disabling silkscreen resizing in response to certain
    virtual key events (e.g. vchrAlarm, vchrFind, etc.) is not a
    recommended solution for the following reasons:
      * such a system is difficult to maintain and is not robust for future
        devices
      * some virtual characters display dialogs or alerts in some
        circumstances but not in others
      * some dialogs or alerts may be generated that do not have a
        corresponding virtual character, such as those generated from Hacks
        or Desk Accessories
      * some dialogs, such as the Find dialog, may require user input.  In
        these cases, the user should be able to restore the Graffiti area.

    Also note that disabling silkscreen resizing when the intended Form
    loses focus is non-trivial; a Form cannot reliably check for winExit
    events because they may be intercepted by the event loop of a dialog
    box or alert.

    When dealing with multiple Forms, it may be desirable for some Forms to
    allow resizing and others not.  In such cases, each Form should
    enable or disable silkscreen resizing when opened. (A data-directed
    approach might be preferable if dealing with a large number of Forms.)
