<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<article id="guikachu">

  <title>The Guikachu 2.0 Manual</title>
  <articleinfo><author>
    <firstname>Gergő</firstname>
    <firstname>Érdi</firstname>
  </author></articleinfo>

  <section id="intro">
  <title>Introduction</title>
  
  <para>
    If you are familiar with PalmOS development, you may have
    encountered one of the numerous resource editors running in the
    Windows or MacOS operating environments,
    and wished for a UNIX application that does the same, because it
    is your operating system of choice. Or maybe you've always created
    RCP files by hand and wondered if there's an easier and faster way.
  </para>

  <para>
    Guikachu is a PalmOS resource editor that runs in the
    UNIX environment, using the
    <ulink url="http://www.gnome.org/">GNOME</ulink> desktop
    framework. At the time of writing this manual,
    Guikachu is the only PalmOS  resource editor
    application for UNIX systems. If you've used
    <ulink url="http://glade.gnome.org/">Glade</ulink>,
    a user interface editor for GNOME, the
    interface of Guikachu will look familiar.
  </para>

  <para>
    Unlike most of the applications available for Windows
    and MacOS, Guikachu is
    <ulink url="http://www.gnu.org/philosophy/free-sw.html">Free Software</ulink>
    as defined by the terms of the GPL.
    You are not only allowed, but encouraged to look at the source
    code, give it away to your peers, friends and colleagues and
    modify it to your liking, as long as you grant these same rights
    to everyone else. See the
    <ulink url="http://www.gnu.org/copyleft/gpl.html">GNU GPL</ulink>
    for the specific license terms.
  </para>

  <para>
    You can find news about the project and the latest releases of the
    application at the
    <ulink url="http://cactus.rulez.org/projects/guikachu/">Guikachu web site</ulink>.
  </para>

</section>
  <section id="using">
  
  <title>Using Guikachu</title>
  
  <section id="starting">
    <title>Starting Guikachu</title>
    <para>
      There are several ways of starting up Guikachu:
    </para>
    <itemizedlist>
      <listitem><formalpara><title>
	  Using the Guikachu menu item in the GNOME Panel menu
	</title><para>
	  Click on the Guikachu icon in the Development category of
	  the GNOME Panel menu to launch Guikachu with an empty
	  document.
	</para></formalpara></listitem>
      
      <listitem><formalpara><title>
	  By opening a Guikachu document from the file
	  manager
	</title><para>
	  Double-click on an existing Guikachu document in
	  Nautilus to start editing the selected document
	  with Guikachu.
	</para></formalpara></listitem>
      
      <listitem><formalpara><title>From the command line</title><para>
	  When you start Guikachu from the command line, you can
	  optionally include the name of a file to start working
	  on. If the file does not exist, Guikachu will create it the
	  first time you save your work.
	</para></formalpara><para>
	  You can also open remote URI's from the command line, as in
	  the following example:
	</para></listitem>
      
      <listitem><formalpara><title>Automatic restart by the session manager</title><para>
	  The last edited file is remembered, and it is automatically
	  loaded when the session manager restarts Guikachu.
	</para></formalpara><para>
	  Refer to the GNOME documentation on setting up the session
	  manager with GNOME.
	</para></listitem>
    </itemizedlist>

    <para>
      Regardless of how you start Guikachu, the application starts
      with the main window displayed.
    </para>
  </section>

  <section id="prc">
    <title>Using PilRC with Guikachu</title>
    <para>
      To make use of the resources that you've created with Guikachu
      in your PalmOS application, you will have to compile it into the
      native machine format of PalmOS. This is not done by Guikachu,
      instead, it outputs a file in the RCP format that's suitable for
      PilRC to process. PilRC is a free,
      portable PalmOS resource compiler.
    </para>
    <para>
      Besides the Guikachu application exporting projects in RPC, a
      small utility program called guikachu2rcp is also
      included. This can be used to create RCP files from Guikachu
      projects on the command line, or to use automated build systems
      like the UNIX Make system.
    </para>
    <para>
      Compiling an RCP file into PalmOS machine code is done as shown
      in the following example (compiling my-app-1.rcp):
    </para>

    <informalexample><programlisting>
pilrc -H my-app-1.rcp.h my-app-1.rcp      
    </programlisting></informalexample>

    <para>
      This will create a couple of files with the ".bin" and
      ".grc" extensions. These will be linked into the main
      application with the build-rcp tool, part of
      the PalmOS SDK.
    </para>
    <para>
      The file "my-app-1.rcp.h" will also be created, which
      is used to associate the symbolic (textual) names of the
      resources to the numerical representation used by PalmOS. It
      contains lines like:
    </para>
    <informalexample><programlisting>
/* pilrc generated file.  Do not edit! */
#define HelpAbout 9973
#define FileSave 9974
#define FileOpen 9975
#define FileDanger 9976      
    </programlisting></informalexample>

    <para>
      Include this header in your C source files to access the
      resources from the application code. See the sample code
      included in the Guikachu source distribution for more
      information.
    </para>

  </section>
  
  <section id="mainwin">
    <title>The Main Window</title>
    <para>
      The main window shows the contents of the current project and
      allows you to do I/O operations and edit/add/remove resources.
    </para>
    <figure><title>
      The main window, with the sample file opened
    </title><graphic fileref="pictures/main-window.png"/></figure>
    <para>
      There are five parts of the main window, from top to bottom: the
      window title (provided by the window manager), the menu bar, the
      tool bar, the resource list, and the status bar. The menu bar
      contains the I/O commands and the tool bar contains shortcuts to
      common operations. The status bar shows the currently selected Guikachu
      object, or descriptions of menu items.
    </para>

    <section id="io">
      <title>Saving and loading</title>
      <para>
	Resources are stored in XML files. Use the Save and Open
	commands from the tool bar or the File menu to save the
	project you're currently working on, or to open a previously
	saved project. The first time you save your project, a file
	selector will pop up asking you to enter the name of the newly
	created file. Although you can use any name you want, it is a
	good idea to use ".guikachu" as the file extension,
	to make sure you can open it from the file manager.
      </para>
      <para>
	Choose "PilRC document" in the File Type
	dropdown list, and select an RCP file from the file list to
	import an RCP file.
      </para>
      <para>
	Guikachu remembers the last couple of files opened, and you
	can quickly access them from the bottom of the File
	menu.
      </para>
      <para>
	To create the RCP files for compiling by PilRC, select
	"Export RCP" from the File menu. You will be asked
	to enter the name of the RCP file to create.
      </para>
      <para>
	Use the New command from the File menu
	or the tool bar to start a new project from scratch.
      </para>
    </section>

    <section id="browsing">
      <title>Browsing resources</title>
      <para>
	The main window lists resources in the current project grouped
	by their type. Use the View menu to change this to a simple
	list sorted by ID.
      </para>
    </section>

    <section id="add-res">
      <title>Adding/removing resources</title>

      <figure><title>
	Adding a new resource
      </title><graphic fileref="pictures/add-res.png"/></figure>
      <para>
	Click the Add button in the tool bar or the
	File menu to add a new resource to the project
	currently opened. Select the resource type from the drop-down
	menu, and type in the ID of the newly created resource. If you
	don't enter an ID, Guikachu automatically assigns a new,
	unique name based on the type of the resource.
      </para>
    </section>
    
  </section>

    <section id="edit">
      <title>The Edit menu</title>
      <para>
	The Edit menu of the main window contains commands for
	manipulating the clipboard and using the undo system.
      </para>
      <para>
	Cut and Copy work like in any other
	application: they place the selected resource onto the
	clipboard, and in the case of Cut, also remove it
	from the current project. You can then use Paste in any other
	Guikachu window to create a duplicate of this resource and
	insert it into the project.
      </para>
      <para>
	Note: Due to the way clipboards in the X Window System work,
	the contents of the clipboard are lost when you quit
	Guikachu.
      </para>
      <para>
	The Edit menu also contains Undo and
	Redo.  Use Undo if you want to revert
	changing something you didn't intend to. If you then realize
	that the change was, in fact, desirable, use Redo
	to apply the change again.
      </para>
      <para>
	Right-click on a resource in the resource listing to pop up a
	menu of available commands. Cut and Copy
	work like the respective items in the Edit menu.
	Click on Remove to delete the selected resource
	from the current project.
      </para>
    </section>
    
  <section id="preferences">
    <title>Setting preferences</title>
    <para>
      Click on Preferences in the Edit menu
      to display the dialog box where you can tune certain aspects of
      Guikachu to your liking.
    </para>
    <figure><title>
      The Preferences dialog box
    </title><graphic fileref="pictures/preferences.png"/></figure>

    <para>
      Currently, there are preference settings only for the <link linkend="form-editor"><citetitle>Form Editor</citetitle></link>. You can change the colors
      used by the form preview by clicking on the colored buttons and
      selecting a new color. These colors are only used when editing
      greyscale Palm projects, otherwise true colors are used.  The
      default zoom factor will be used when opening form editor
      windows, but can be changed individually for each preview window
      as well.
    </para>
    <para>
      Click on OK or Apply to make the current
      settings take effect (OK also closes the
      window). Click on Cancel to dismiss the dialog without
      using the new settings.
    </para>
  </section>
  
</section>
  <section id="resource-win">
  <title>Resource Windows</title>
  <para>
    Resources are edited by double-clicking on them in the main
    window. This pops up a new window containing controls to view
    and change the attributes of the resource. With the exception of
    the <link linkend="menu-editor"><citetitle>menu editor</citetitle></link> and the <link linkend="form-editor"><citetitle>form editor</citetitle></link> (see their description
    later), these property editors share a common set of controls.
  </para>
  <para>
    A special resource is the one holding application data such as
    icon caption (as shown by the Program Manager on Palm handhelds)
    and the version number. Since it wouldn't make sense to have either
    more or less than one of these, they are not shown in the main window's
    tree view. Instead, you can access it by double-clicking on the
    "root" of the list, the item that shows the icon caption
    (or "Application" by default).
  </para>
  <figure><title>
    Tree item for application-level resources
  </title><graphic fileref="pictures/main-window-app-res.png"/></figure>

    <para>
    
    A resource window contains controls that show the current value
    of different aspects, or "properties" of the
    resource. The left-hand side of the window contains the names of
    the properties, and the right-hand side has the property
    controls. Press Alt and the underlined letter from
    the property label to move the input focus to the selected
    property's control.
  </para>
  <para>
    Some resource windows are broken into multiple pages of property
    editors. Click on the tabs at the top of the window to change
    pages.
  </para>
  
  <section>
    <title>Text properties</title>
    
    <para>
      There are three types of textual properties in Guikachu:
      resource ID's, single-line small strings and multi-line, long
      texts.
    </para>
    
    <figure><title>
      String property editor
    </title><graphic fileref="pictures/prop-string.png"/></figure>
    <para>
      Single-line string properties are edited by simply focusing
      the text entry (by clicking on it, or pressing the
      Alt key and the underlined letter of the left-side
      label) and typing. Changes are instantly applied, which is
      very useful for widgets, since you can see the results in real
      time in the form preview.
    </para>
    
    <figure><title>
      Resource ID editor
    </title><graphic fileref="pictures/prop-id.png"/></figure>
    <para>
      Although they look just like any other string property,
      resource ID's are a special case because changes are not
      instantly applied. This is done to make validation possible:
      the uniqueness of each ID is automatically enforced by
      Guikachu when you press Enter in a resource ID
      field. If there is another resource with the same ID already
      existing in the current project, a message is shown and the
      previous value is restored.
    </para>
    
    <figure><title>
      Text property editor
    </title><graphic fileref="pictures/prop-text.png"/></figure>
    <para>
      Certain resources can have long, multi-line string
      properties. These are edited just like single-line strings,
      but your input can include Enter and
      Tab.
    </para>

    <para>
      For user-visible strings (i.e. not ID's), you can use the
      \ character to include "escape
      sequences". The two most important notions are
      <emphasis>\nnn</emphasis> where <emphasis>nnn</emphasis> is an octal number, and
      <emphasis>\xnn</emphasis>, where <emphasis>nn</emphasis> is a hexadecimal
      number. Since Guikachu only accepts 7-bit input, you will need
      to use these escape codes to include characters from the Latin-1
      set. Note that as of 1.2, <emphasis>\r</emphasis> is not yet supported
      by Guikachu.
    </para>
  </section>
  
  <section>
    <title>Numeric properties</title>
    <figure><title>
      Numeric property editor
    </title><graphic fileref="pictures/prop-spin.png"/></figure>
    <para>
      Numeric properties can be edited either by entering the new
      value directly to the entry field, or by clicking the up/down
      arrows with the mouse. Since some properties only accept a
      certain range of values, the value entered may be changed
      after you set it to a value outside the valid range.
    </para>
  </section>
  
  <section>
    <title>References</title>
    <figure><title>
      A reference to a string resource
    </title><graphic fileref="pictures/prop-ref.png"/></figure>
    <para>
      Some properties are references to other resources, for example
      the "Help" property of a dialog points to a string
      resource that will be displayed when the user taps the help
      icon. Setting these is done by selecting from the drop-down
      list of available resources of the appropriate type. Changing
      a resource's ID automatically changes every other property
      pointing to it.
    </para>
    <para>
      To quickly access the referenced resource, click the
      Edit button next to the drop-down list. This pops
      up the editor window for the currently selected resource.
    </para>
  </section>
  
  <section>
    <title>Toggles</title>
    <figure><title>
      Simple toggle button
    </title><graphic fileref="pictures/prop-toggle.png"/></figure>
    <para>
      Properties that are of binary nature (i.e. those that can
      either be set or unset) can be changed by clicking on the
      yes/no toggle button. The button shows the current state of
      the property.
    </para>
    
    <figure><title>
      Compound property editor with manual/automatic switch
    </title><graphic fileref="pictures/prop-size.png"/></figure>
    <para>
      The size of some widgets can be either manually specified or
      calculated from its contents. Automatic size is the
      default. To enter a manual value, first check the check-box on
      the left of the size entry, and then change the value in the
      entry.
    </para>
    <para>
      The first time you change an automatic value to a manual one,
      the manual value is initialized with the currently calculated
      value.
    </para>
  </section>
  
  <section>
    <title>Selecting from a list</title>
    <figure><title>
      Drop-down list
    </title><graphic fileref="pictures/prop-dropdown.png"/></figure>
    <para>
      Some properties can only have values from a fixed
      set. Clicking on the current value pops up a list of options.
    </para>
  </section>
  
  <section>
    <title>String lists</title>
      <figure><title>
      A string list editor
    </title><graphic fileref="pictures/prop-stringlist.png"/></figure>
    <para>
      Some properties, like the buttons of a dialog, contain a list of
      strings. To insert a new item after the currently selected
      string, click on the Add button, then type in the new
      string. To modify an existing item, select it from the list and
      in the new string. The Up and Down buttons
      change the position of the currently selected item.
    </para>
    <para>
      The dialog editor also has a special Default
      button. Press this to mark the currently selected item as the
      default response.
    </para>
  </section>
</section>
  <section id="menu-editor">
  <title>The Menu Editor</title>

  <figure><title>
    Editing the menu tree of an application
  </title><graphic fileref="pictures/menu-editor.png"/></figure>
  
  <para>
    The menu editor is a bit different from the other resource
    editors, because rather than being a collection of properties, a
    menu resource stores a tree of sub-menus and menu items.
  </para>

  <section>
    <title>Creating a sub-menu</title>
    <para>
      After you create a menu resource, the first thing you will want
      to do is populate it with sub-menus. There are no top-level menu
      items in PalmOS: all menu items must be placed in a sub-menu.
    </para>
    <para>
      Click the Add Submenu button to add a sub-menu to the
      edited menu resource. Editing the new submenu will start
      automatically.  Click on the arrow next to the button to access
      stock menus common to PalmOS applications.
    </para>
    <para>
      Sub-menus are only part of the user interface, they do not emit
      <emphasis>event</emphasis>s themselves. Thus, sub-menus only have a label
      and don't have an ID.
    </para>
  </section>

  <section>
    <title>Populating sub-menus</title>
    <para>
      Menus can hold an arbitrary number of menu items and
      separators. Use the Add Item button to create a new
      menu item in the currently selected submenu.
    </para>
    <para>
      A menu item has a label (the caption shown to the user), a
      resource ID (which is used by the application's event handler to
      distinguish menu item events) and an optional shortcut. The
      shortcut is a single letter that, when entered combined with the
      shortcut (\) character, emits the same event as if
      the corresponding menu item was tapped. Thus, in the example
      above, the user entering \u is the same as selecting
      "Undo" from the "Edit" menu.
    </para>
    <para>
      Separators are used to group related menu items based on their
      function. Clicking the arrow next to the Add Item
      button to insert a new separator in the currently selected sub-menu.
    </para>
    <para>
      Reordering menu items and submenus is done by grabbing the item
      with the left mouse button, and dragging it to a new position,
      or by clicking the Up and Down buttons on
      the right-hand side of the menu editor.
    </para>
    <para>
      Sub-menus and menu items can be deleted with the
      Remove button. Removing a sub-menu deletes all its
      children as well.
    </para>
  </section>
  
  <section>
    <title>The preview area</title>
    <para>
      The area above the menu editor shows a simulated PalmOS screen
      displaying the currently edited menu. Click on a submenu title
      to view the menu items. Just like the form editor, this view
      shows the menus exactly as they will appear on a real PalmOS
      handheld.
    </para>
    <para>
      When editing larger menus, you might need a little extra
      space. The preview area can be toggled on/off by clicking on the
      small triangle or the Menu Preview title.
    </para>
  </section>
  
</section>
  <section id="bitmaps">
  <title>Bitmaps</title>

  <para>
    Pictures (called "Bitmaps" in PalmOS terminology) are
    stored as resources just like any other type. You can use bitmaps
    in your user interface by either displaying them in a <link linkend="widget-formbitmap"><citetitle>Bitmap widget</citetitle></link>, or using them as
    custom
    <link linkend="widget-button"><citetitle>buttons,</citetitle></link>
    <link linkend="widget-pushbutton"><citetitle>pushbuttons,</citetitle></link>
    <link linkend="widget-selector-trigger"><citetitle>selector triggers,</citetitle></link> or
    <link linkend="widget-popup-trigger"><citetitle>popup triggers</citetitle></link>.
  </para>

  <section>
    <title>Basics of image handling</title>

    <figure><title>
      A resource containing a single bitmap
    </title><graphic fileref="pictures/bitmap-window.png"/></figure>
    <para>
      Since Guikachu is not an image manipulation suite,
      you have to create and edit the picture files externally. This
      is done by creating an image file in your application of choice,
      then clicking on the Load button in the Bitmap
      Editor. A simple file selector window pops up, allowing you to
      load the image file. Once it's loaded, the image data resides in
      the .guikachu file itself, so everything stays in one single
      easy-to-transport file. To re-create the standalone image file
      (e.g. for further editing), click on the Export
      button.
    </para>
  </section>
  
  <section>
    <title>Color depths</title>
    <para>
      PalmOS defines several color depths for images. When you create
      a Bitmap resource, you have to choose an appropriate color depth
      from the Type dropdown list. The Preview area will
      show the picture in the currently selected color palette.
    </para>

    <para>
      Different Palm handhelds may have different screens, and not
      every device may be capable of displaying pictures in hundreds
      or thousands of colors. The Bitmap Group resource allows you to
      pack pictures of different depth into a single resource. At
      run-time, the most colorful one will be selected, based on the
      actual Palm device's screen capabilities.
    </para>
    <figure><title>
      A Bitmap Group contains images in several color depths
    </title><graphic fileref="pictures/bitmapgroup-window.png"/></figure>
    <para>
      You can use Bitmap Groups everywhere where a Bitmap might be
      used. One limitation of PalmOS is that 16-color greyscale and
      color images are mutually exclusive, thus in any given Bitmap
      Group, only one of the two may be used.
    </para>
  </section>
  
</section>
  <section id="form-editor">
  <title>Using the Form Editor</title>
  
  <para>
    The form editor allows you to create forms in a WYSIWYG
    way. "Form" is the PalmOS terminology for windows:
    rectangular areas of the screen that hold related user interface
    elements, the so-called "widgets". WYSIWYG (What You See
    Is What You Get) means you can immediately see the results of your
    actions in a preview window showing you what the screen of the
    PalmOS device will look like.
  </para>
  <figure><title>
    Previewing a form while editing it in Guikachu
  </title><graphic fileref="pictures/form-editor-preview.png"/></figure>
  <para>
    You can use the zoom spinner to enlarge the simulated PalmOS
    screen. If the form editor window is too small to display all of
    the preview at once, scroll bars are displayed so you can pan
    around.
  </para>
  
  <para>
    Click on the Widgets tab to display a textual listing
    of the widgets contained in the current form. This can be very
    useful for locating and selecting widgets in overcrowded forms.
  </para>
  <figure><title>
    Listing the widgets of the same form
  </title><graphic fileref="pictures/form-editor-tree.png"/></figure>
  <para>
    Each item of the list also contains an icon showing the type of
    the widget. The <link linkend="widget-selecting"><citetitle>selection</citetitle></link> is
    synchronized between the widget list and the preview tab.
  </para>

  <para>
    Depending on the screen capabilities of the <link linkend="res-app"><citetitle>target machine</citetitle></link>, the form preview will be
    displayed in either color or greyscale mode. In greyscale mode,
    color <link linkend="bitmaps"><citetitle>bitmaps</citetitle></link> are shown in greyscale,
    and widgets are drawn using the foreground and background colors
    set in the <link linkend="preferences"><citetitle>Preferences dialog</citetitle></link>.
  </para>
  <figure><title>
    The same form as above, in greyscale mode
  </title><graphic fileref="pictures/form-editor-preview-greyscale.png"/></figure>
  
  <section>
    <title>The Widget Palette</title>
    <para>
      Just like a painter's palette, the widget palette is used to
      select what you want to "draw" on your canvas: the
      screen of the PalmOS device. 
    </para>

    <figure><title>
      The Widget Palette
    </title><graphic fileref="pictures/palette.png"/></figure>
    <para>
      Widgets available on the widget palette, from left to right and
      top to bottom, are:
    </para>
    <itemizedlist>
      <listitem><para>
	<link linkend="widget-label"><citetitle>Label</citetitle></link>,
	<link linkend="widget-text-field"><citetitle>Text Field</citetitle></link>,
	<link linkend="widget-graffiti"><citetitle>Graffiti state indicator</citetitle></link>
      </para></listitem>
      <listitem><para>
	<link linkend="widget-button"><citetitle>Button</citetitle></link>,
	<link linkend="widget-pushbutton"><citetitle>Pushbutton</citetitle></link>,
	<link linkend="widget-selector-trigger"><citetitle>Selector trigger</citetitle></link>
      </para></listitem>
      <listitem><para>
	<link linkend="widget-checkbox"><citetitle>Check box</citetitle></link>,
	<link linkend="widget-popup-trigger"><citetitle>Popup trigger</citetitle></link>,
	<link linkend="widget-list"><citetitle>List</citetitle></link>
      </para></listitem>
      <listitem><para>
	<link linkend="widget-scrollbar"><citetitle>Scroll bar</citetitle></link>,
	<link linkend="widget-table"><citetitle>Table</citetitle></link>,
	<link linkend="widget-formbitmap"><citetitle>Bitmap</citetitle></link>
      </para></listitem>
      <listitem><para>
	<link linkend="widget-gadget"><citetitle>Gadget (custom widget)</citetitle></link>
      </para></listitem>
    </itemizedlist>
    
    <para>
      To put a new widget on a form, first click on the widget's icon
      in the palette, then click on the preview window of the
      appropriate form. After the widget is created, the palette
      selection reverts to the
      <link linkend="widget-selecting"><citetitle>"selection" tool</citetitle></link>. If you
      hold down the Ctrl key while clicking on the palette,
      the selected widget type becomes "sticky", i.e. it
      will not automatically switch back to the selector. Use this to
      place multiple widgets of the same kind on a form.
    </para>
  </section>

  <section id="widget-selecting">
    <title>Selecting and Deleting Widgets</title>

    <section id="selection">
      <title>Changing the selection</title>
      <para>
	Widget operations such as moving or deleting are always done on
	the current widget selection. Selecting a widget also opens its
	<link linkend="widget-editing"><citetitle>editor window</citetitle></link>. 
      </para>
      <para>
	Click on the "Selector" icon to select widgets in the
	form preview. You can also use the widget list tab of the form
	editor window to change the selection. Clicking with the left
	mouse button selects the clicked widget and un-selects
	everything else. Press the Ctrl key while clicking to
	add/remove the widget to the current selection. This works in
	both the preview area and the widget list.
      </para>

      <para>
	To select multiple widgets at one time, begin dragging the
	pointer with the left mouse button pressed, anywhere outside a
	widget. You'll see a rectangle showing the current area. When
	you release the mouse button, everything inside the rectangle
	will be selected. Again, if you hold down the Ctrl
	key, the widgets inside the rectangle are added to the current
	selection instead of replacing it.
      </para>
      
      <figure><title>
	Multiple widgets selected
      </title><graphic fileref="pictures/form-editor-selection.png"/></figure>
      
      <para>
	If the current selection is empty or doesn't include the
	widget you clicked to access an operation, the clicked widget
	replaces the current selection, i.e. if you begin dragging an
	unselected widget it immediately becomes the selected one.
      </para>
    </section>

    <section>
      <title>Deleting widgets</title>
      <para>
	In either the form preview or the widget list view, click on a
	widget with the right mouse button to pop up a menu of widget
	commands. As of version 1.0, this menu includes a single
	Remove item. Select this to delete the currently
	selected widgets from the project.
      </para>
    </section>
  </section>


  <section id="widget-rightclick">
    <title>The Right-Click Menu</title>
    <para>
      Select Cut or Copy from the right-click menu to put the selected
      widgets on the clipboard (and, in the case of Cut, to remove
      them from the current project). Right-click on a form in either
      the same project or another and select Paste to insert a
      duplicate of the widgets on the clipboard.
    </para>
    <para>
      If more than one widget is selected, the right-click menu will
      also contain items to help you in lining up widgets. Each of
      these aligning commands will move the selected widgets to be
      on the same horizontal or vertical line.
    </para>
  </section>
  
  <section id="widget-operation">
    <title>Moving and Resizing</title>
    <para>
      When laying out your widgets on a form, it's often easier to
      visually modify the layout instead of manually entering position
      and size information into the
      <link linkend="widget-editing"><citetitle>property editor windows</citetitle></link>.
    </para>
    
    <section>
      <title>Moving widgets</title>
      <para>
	You can move widgets either by changing their <emphasis>X</emphasis>
	and <emphasis>Y</emphasis> properties, or by dragging them around on
	the form preview. Drag one of the currently selected widgets
	with the left mouse button to move all of the selection. This
	is useful for moving widgets while preserving their relative
	positions.
      </para>
    </section>

    <section>
      <title>Resizing</title>
      <para>
	Some widgets' dimensions are determined by their content: for
	example, a <link linkend="widget-label"><citetitle>label</citetitle></link>'s size will
	always be determined by the text it contains. The size of
	widgets like <link linkend="widget-button"><citetitle>buttons</citetitle></link>, on the
	other hand, can be changed to make a widget smaller or larger
	than their automatic dimensions.
      </para>
      <para>
	If you click on a resizeable widget, small grips are shown in
	its four corners, as seen on the screenshot below. Drag one of
	these handles to resize the widget in the given direction.
      </para>
      <figure><title>
	Resize grips shown for a selected button
      </title><graphic fileref="pictures/form-editor-resize.png"/></figure>
      <para>
	You can hold down the Shift key while resizing to
	keep the original aspect ratio (the relative width and height)
	of the widget. You can release Shift anytime during
	the resizing to get back to non-constrained resizing.
      </para>
    </section>

  </section>

  <section id="widget-editing">
    <title>Editing Widget Properties</title>
    <para>
      Clicking on a widget not only changes the <link linkend="selection"><citetitle>selection</citetitle></link>: it also opens the editor
      window for the widget. Widget editors are just like <link linkend="resource-win"><citetitle>resource windows</citetitle></link>, and contain the same
      types of property editors.
    </para>
    <para>
      The only difference between resource
      editors and widget editors is that the latter are not popped up
      in separate windows, instead, there is a single property window
      shown for every form opened. Thus, when you edit a widget, its
      property controls replace the controls of the previous widget.
    </para>
  </section>
  
</section>
  <section id="resources">

  <title>Resource Reference</title>
  
  <para>
    A PalmOS resource file contains, unsurprisingly, resources. A
    "resource" is a general term for static data stored
    inside the application's executable. Each resource is described by
    various properties.
  </para>

  <para>
    To access the resources from the application, each resource has a
    unique ID. This ID is, internally, an unsigned integer. To make
    programmers' life easier, the resources also have a
    human-readable, textual ID. Guikachu only stores the text ID's,
    the numerical ID's are created by PilRC when it compiles the RCP
    file. A supplemental C header is also created by PilRC that
    contains the mapping between the numerical and the textual ID's.
  </para>

  

  <section id="res-app">
    <title>Top-level properties</title>
    
      <para>
	There are some singleton properties that are associated with
	the project itself, and not one of the resources. These are
	automatically used by the application, i.e. you don't need to
	do anything in your code to make these apply.
      </para>
      <para>
	You can edit these by double-clicking on the root element of
	the resource tree (the one that initially reads
	<emphasis>Application</emphasis>).
      </para>
    
    <variablelist>
      <varlistentry id="res-app-iconcaption">
	<term>Icon caption</term>
	<listitem>
	  <para>
	    The string that will be displayed in the application launcher and the
	    various statistics windows (e.g. the memory usage list)
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry id="res-app-version">
	<term>Version</term>
	<listitem>
	  <para>
	    The string displayed in the Version view of the Info window
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry id="res-app-vendor">
	<term>Vendor ID</term>
	<listitem>
	  <para>
	    The four character long, case-sensitive vendor ID's should be globally
	    unique -- contact PalmOS.com to register your vendor ID.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry id="res-app-target">
	<term>Target machine</term>
	<listitem>
	  <para>
	    There are some differences between handheld platforms that
	    use the RCP format to describe resources, most notably,
	    the screen size and resolution of some devices are not the
	    same as that of vanilla Palm handhelds. Set
	    this property to the device your project is targeting.
	  </para>
	  <para>
	    You can either choose from a list of devices with
	    pre-configured values, or choose "Custom
	    machine" to create a custom definition.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>
    
  </section>
  
  <section id="res-blob">
    <title>RCP code fragment</title>
    
      <para>
	As of version 2.0, Guikachu does not support every RCP
	feature. To handle this, you can store arbitrary RCP fragments
	in your Guikachu files. No effort is made to parse
	these, so you will have to check the syntax yourself. Of
	course, there's nothing to stop you from storing supported
	resources like Forms in fragments, but this pretty much takes away
	the whole point of Guikachu.
      </para>
      <para>
	Note that you can store multiple fragments in a single Guikachu
	document, to make things more organized.
      </para>
    
    <variablelist>
      <varlistentry id="res-blob-id">
	<term>Resource ID</term>
	<listitem>
	  <para>
	    Unlike the ID's of "real" resources, the ID of a
	    fragment resource is not used in any way in the RCP
	    output. Instead, ID's simply provide a way for you to
	    label your blobs.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>
    
  </section>
  
  <section id="res-string">
    <title>String</title>
    
      <para>
	String resources are used to store static, user-visible strings,
	separated from the code. To access them from your application,
	use the following code:
      </para>
      <informalexample><programlisting>
Char *msg = MemHandleLock (DmGetResource (strRsc, string_id));
/* Do something with the string */
MemPtrUnlock (msg);
      </programlisting></informalexample>
    
    <variablelist>
      <varlistentry id="res-string-id">
      <term>Resource ID</term>
      <listitem>
	<para>
	  A unique string ID used for accessing the resource at
	  run-time from the program
	</para>
      </listitem>
    </varlistentry>
      <varlistentry id="res-string-string">
	<term>String</term>
	<listitem>
	  <para>
	    The contents of the string
	  </para>
	</listitem>
      </varlistentry>      
    </variablelist>
  </section>

  <section id="res-stringlist">
    <title>String list</title>
      
      <para>
	String lists contain several, usually related, strings. 
        The following code shows how you can access the items of a
        string list from your application:
      </para>
      <informalexample><programlisting>
MemHandle my_table_handle;
MemPtr    my_table_ptr;
Int16     prefix_length, item_count;
	
/* Read and lock string table resource */
my_table_handle = DmGetResource('tSTL', my_stringtable_id);
my_table_ptr    = (MemPtr) MemHandleLock(memTableHandle);

prefix_lenght = StrLen ((Char*) my_table_ptr);

/* The number of items is stored in two bytes after the prefix */
item_count    = (*((UInt8 *)(my_table_ptr + prefix_length + 1)) &lt;&lt; 8) |
                (*((UInt8 *)(my_table_ptr + prefix_length + 2)));

my_table_items = SysFormPointerArrayToStrings (my_table_ptr + prefix_length + 3, item_count);

/* The original resource handle is no longer needed */
MemHandleUnlock (my_table_handle);
DmReleaseResource (my_table_handle);

/*
 * You are now only responsible for freeing my_table_items
 * when you're done with it. Everything else has been properly
 * cleared up.
 */	  
      </programlisting></informalexample>
    
    <variablelist>
      <varlistentry id="res-stringlist-id">
      <term>Resource ID</term>
      <listitem>
	<para>
	  A unique string ID used for accessing the resource at
	  run-time from the program
	</para>
      </listitem>
    </varlistentry>
      <varlistentry id="res-stringlist-prefix">
	<term>Prefix</term>
	<listitem>
	  <para>
	    This string is prepended to every list item when items are
	    retrieved by the <emphasis>SysStringByIndex</emphasis> function.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>
  </section>

  <section id="res-dialog">
    <title>Dialog</title>
    
      <para>
	A dialog is a modal window, with a title, some text, an icon,
	and one or more buttons. It can also include a reference to a
	<link linkend="res-string"><citetitle>string resource</citetitle></link> that is used in the pop-up help.
      </para>
    
    <variablelist>
      <varlistentry id="res-dialog-id">
      <term>Resource ID</term>
      <listitem>
	<para>
	  A unique string ID used for accessing the resource at
	  run-time from the program
	</para>
      </listitem>
    </varlistentry>
      <varlistentry id="res-dialog-title">
	<term>Title</term>
	<listitem>
	  <para>
	    The title of the dialog, displayed in the title bar 
	  </para>
	</listitem>
      </varlistentry>
      
      <varlistentry id="res-dialog-type">
	<term>Type</term>
	<listitem>
	  <para>
	    Specifies the icon shown in the dialog. Please see the PalmOS
	    Reference for a detailed description on when to use which mode
	  </para>
	</listitem>
      </varlistentry>
      
      <varlistentry id="res-dialog-help_id">
	<term>Help ID</term>
	<listitem>
	  <para>
	    The (optional) resource ID of a
	    <link linkend="res-string"><citetitle>string</citetitle></link> that describes the
	    usage of the dialog. If specified, the title bar of the
	    dialog will include a ? button to display
	    the help.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry id="res-dialog-text">
	<term>Text</term>
	<listitem>
	  <para>
	    The text to be displayed in the dialog (to the right of the
	    dialog icon). You can use up to three ^
	    marks (^1, ^2 and
	    ^3 to indicate placeholders for strings
	    that are filled at run-time.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry id="res-dialog-buttons">
	<term>Buttons</term>
	<listitem>
	  <para>
	    The Buttons list is an ordered list of strings. Each of
	    these strings will create a button at the bottom of the
	    dialog. The return value of <emphasis>FrmAlert</emphasis>
	    will be the index of the button pressed (starting at 0).
	  </para>
	  <para>
	    If the user exits the dialog by switching to another
	    application, <emphasis>FrmAlert</emphasis> will return
	    with the default button's index.
	  </para>
	</listitem>
      </varlistentry>	
    </variablelist>
  </section>

  <section id="res-menu">
    <title>Menu bar</title>
    
      <para>
	A menu bar is a horizontal strip on the top of the screen,
	containing drop-down menus. Since selecting a menu item takes
	numerous clicks, often-used operations should be accessible
	through other means.
      </para>
      <para>
	The menus are single-level deep. Each menu item has a unique
	ID, a user-visible label, and an optional shortcut letter,
	which can be accessed using the shortcut
	(/) graffiti sign.
      </para>
      <para>
	The actual implementation of the menu items are done by
	looking at the <emphasis>itemID</emphasis> in the
	<emphasis>menuEvent</emphasis> handler of the form owning the menu bar.
      </para>
    
    <variablelist>
      <varlistentry id="res-menu-id">
      <term>Resource ID</term>
      <listitem>
	<para>
	  A unique string ID used for accessing the resource at
	  run-time from the program
	</para>
      </listitem>
    </varlistentry>
    </variablelist>
  </section>

  <section id="res-bitmap">
    <title>Bitmaps and Bitmap Groups</title>
    
      <para>
	Bitmaps are pictures stored inside resource files. They can be
	both accessed by the application pixel-by-pixel, or referenced
	in other parts of a resource file and thus displayed by PalmOS
	in forms. Guikachu is not a picture editing application, so
	you must first create the picture separately, then load it via
	Guikachu into a Bitmap or a Bitmap Group.
      </para>
      <para>
	Bitmaps in PalmOS are stored in one of several color depths,
	including both greyscale and color ones. A Bitmap resource
	contains a single image in a single color depth. A Bitmap
	Group can contain more than one image, and PalmOS
	automatically chooses the best (most colorful) for the given
	device's capability.
      </para>
      <para>
	Due to a limitation in PalmOS itself, 16-color greyscale and
	color images are mutually exclusive, so you can only store one
	of the two in any given Bitmap Group.
      </para>
    

    <variablelist>     
      <varlistentry id="res-bitmap-id">
      <term>Resource ID</term>
      <listitem>
	<para>
	  A unique string ID used for accessing the resource at
	  run-time from the program
	</para>
      </listitem>
    </varlistentry>
      
      <varlistentry id="res-bitmap-depth">
	<term>Type</term>
	<listitem>
	  <para>
	    For single-bitmap resources, this property stores the type
	    (color depth) of the image. The actual image data may
	    contain more colors than specified here, and those colors
	    will not be lost, but won't be used when displaying the image.
	  </para>
	</listitem>
      </varlistentry>      
    </variablelist>
  </section>
  
  <section id="res-form">
    <title>Form</title>
    
      <para>
	Form is the PalmOS term for windows. A form
	represents a rectangular area on the screen that can hold an
	arbitrary number of widgets. The maximum size of a form is 160
	pixels high by 160 pixels wide: this is the same as the size
	of the Palm screen itself.
      </para>
      <para>
	You can also use a form as a modal dialog via the
	<emphasis>FrmDoDialog</emphasis> function. This works just like
	<emphasis>FrmAlert</emphasis> and will block your application until a
	button is pressed on the form. The return value of the
	function will be the ID of the button pressed (or the
	<link linkend="res-form-default_button"><citetitle>default button</citetitle></link>'s
	ID if the form is closed by switching to another application).
      </para>
    
    <variablelist>
      <varlistentry id="res-form-id">
      <term>Resource ID</term>
      <listitem>
	<para>
	  A unique string ID used for accessing the resource at
	  run-time from the program
	</para>
      </listitem>
    </varlistentry>

      <varlistentry id="res-form-title">
	<term>Title</term>
	<listitem>
	  <para>
	    The title of the form, shown on the top of it. Its actual
	    rendering is dependent on the form's modalness.
	  </para>
	  <para>
	    If not set, some form decorations are not drawn, thus
	    giving you even more screen real estate to place your
	    widgets on. Category selectors are often placed in the
	    title area's right edge.
	  </para>
	</listitem>
      </varlistentry>
      
      <varlistentry id="res-form-help_id">
	<term>Help ID</term>
	<listitem>
	  <para>
	    If this is set to a valid <link linkend="res-string"><citetitle>string resource</citetitle></link>,
	    and the form is <link linkend="res-form-modal"><citetitle>modal</citetitle></link>,
	    a help button is displayed in the title area of the form,
	    which, when clicked, pops up a dialog containing the help text.
	  </para>
	</listitem>
      </varlistentry>
      
      <varlistentry id="res-form-menu_id">
	<term>Menu ID</term>
	<listitem>
	  <para>
	    The ID of a <link linkend="res-menu"><citetitle>menu resource</citetitle></link>
	    associated with the form.
	  </para>
	</listitem>
      </varlistentry>
      
      <varlistentry id="res-form-modal">
	<term>Modal</term>
	<listitem>
	  <para>
	    Modal forms are used for "blocking" dialogs,
	    when events outside the topmost form are not
	    processed. Modal forms have different decoration than
	    non-modal ones. <link linkend="res-dialog"><citetitle>Dialog resources</citetitle></link>
	    provide an easy-to-use mechanism for displaying simple
	    modal forms.
	  </para>
	</listitem>
      </varlistentry>
	
      <varlistentry id="res-form-frame">
	<term>Frame</term>
	<listitem>
	  <para>
	    Non-modal forms can have an optional one-pixel wide
	    frame. Modal forms always have a frame with a width of
	    two pixels, regardless of this property's value.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry id="res-form-save_behind">
	<term>Save behind</term>
	<listitem>
	  <para>
	    If checked, the form will save the screen contents before
	    it is drawn, and then restore it when closed. Use this for
	    pop-up dialogs, otherwise they might cause artifacts on
	    the screen.
	  </para>
	</listitem>
      </varlistentry>
	
      <varlistentry id="res-form-default_button">
	<term>Default button</term>
	<listitem>
	  <para>
	    It is possible to use a form as a custom modal
	    <link linkend="res-dialog"><citetitle>dialog</citetitle></link> via the
	    <emphasis>FrmCustomAlert</emphasis> function. In this case, this
	    property sets the button the function should return when
	    the users switches to another application instead of
	    clicking on a dialog button.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry id="res-form-pos">
	<term>X and Y</term>
	<listitem>
	  <para>
	  Horizontal and vertical position, in pixels, counted from
	  left to right and top to bottom. Due to the size of the
	  screen of PalmOS devices, both X and Y are integer values
	  between 0 and 159.
	  </para>
	</listitem>
      </varlistentry>
      
      <varlistentry id="res-form-size">
	<term>Width and height</term>
	<listitem>
	  <para>
	    Horizontal and vertical size, in pixels. Due to the size
	    of the screen of PalmOS devices, both width and height are
	    integer values between 1 and 160.
	  </para>
	</listitem>
      </varlistentry>
      
    </variablelist>
  </section>
    
</section>
  <section id="widgets">
  <title>Widget Reference</title>

  
  <para>
    A widget is a unit of a user interface, a single element doing a
    single thing, for example, a tappable button, or an editable text
    field. A form contains various widgets, the user interacts with
    them, and the application is notified via <emphasis>events</emphasis>. See
    the PalmOS documentation and the example application included with
    Guikachu for more information on handling widget events.
  </para>
  
  

  <section id="widget-label">
    <title>Label</title>
    
      <para>
	Labels are static text that can't interact with the user and
	can't be changed by the application at run-time either. For
	non-static labels, use a non-editable
	<link linkend="widget-text-field"><citetitle>text field</citetitle></link>.
      </para>
    
    <variablelist>
      <varlistentry id="widget-label-id">
      <term>Resource ID</term>
      <listitem>
	<para>
	  A unique string ID used for accessing the resource at
	  run-time from the program
	</para>
      </listitem>
    </varlistentry>
      <varlistentry id="widget-label-usable">
      <term>Usable</term>
      <listitem>
	<para>
	  Non-usable widgets are not rendered on the screen and don't
	  receive events. You can set/unset the "usable"
	  property at run-time with the <emphasis>CtlSetUsable</emphasis>
	  function.
	</para>
      </listitem>
    </varlistentry>

      <varlistentry id="widget-label-text-font">
      <term>Text and font</term>
      <listitem>
	<para>
	  The textual contents of the widget. It will be rendered
	  using the specified font.
	</para>
	<para>
	  Guikachu currently only supports the built-in fonts.
	</para>
      </listitem>
    </varlistentry>
      
      <varlistentry id="widget-label-pos">
      <term>X and Y</term>
      <listitem>
	<para>
	  Horizontal and vertical position relative to the parent
	  form, in pixels, counted from left to right and top to
	  bottom. Due to the size of the screen of PalmOS devices,
	  both X and Y are integer values between 0 and 159.
	</para>
      </listitem>
    </varlistentry>
    </variablelist>
    
  </section>

  <section id="widget-text-field">
    <title>Text field</title>
    
      <para>
	A text field contains text that is changeable at run-time,
	either by the application or by the user.
      </para>
      <para>
	There are several ways to set/get the currently displayed text
	of a text field, see the PalmOS SDK for details.
      </para>     
    
    <variablelist>
      <varlistentry id="widget-text-field-id">
      <term>Resource ID</term>
      <listitem>
	<para>
	  A unique string ID used for accessing the resource at
	  run-time from the program
	</para>
      </listitem>
    </varlistentry>
      <varlistentry id="widget-text-field-usable">
      <term>Usable</term>
      <listitem>
	<para>
	  Non-usable widgets are not rendered on the screen and don't
	  receive events. You can set/unset the "usable"
	  property at run-time with the <emphasis>CtlSetUsable</emphasis>
	  function.
	</para>
      </listitem>
    </varlistentry>

      <varlistentry id="widget-text-field-font">
	<term>Font</term>
	<listitem>
	  <para>
	    The font used to display the contents of the text field
	  </para>
	  <para>	    
	    Guikachu currently only supports the three default built-in
	    fonts: #0 is the "normal", #1 is the "bold" and
	    #2 is the "large" font.
	  </para>
	</listitem>
      </varlistentry>
	
      <varlistentry id="widget-text-field-editable">
	<term>Editable</term>
	<listitem>
	  <para>
	    Controls whether the user is able to change the field's
	    contents.
	  </para>
	</listitem>	  
      </varlistentry>
      
      <varlistentry id="widget-text-field-multi-line">
	<term>Multi-line</term>
	<listitem>
	  <para>
	    Multi-line text fields automatically wrap input at the end
	    of visible lines. They also accept newline and
	    tab as input.
	  </para>
	</listitem>	  
      </varlistentry>
      
      <varlistentry id="widget-text-field-numeric">
	<term>Numeric-only</term>
	<listitem>
	  <para>
	    Set this property to restrict input by the user to numbers
	    only. Since it only controls user input, it makes sense
	    only for <link linkend="widget-text-field-editable"><citetitle>editable</citetitle></link> 
	    text fields.
	  </para>
	</listitem>	  
      </varlistentry>

      <varlistentry id="widget-text-field-length">
	<term>Maximum length</term>
	<listitem>
	  <para>
	    Maximum allowed length of text entered by the user. Set
	    this to 0 to force no restrictions (actually, there is
	    still a restriction on length due to the PalmOS
	    architecture).
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry id="widget-text-field-underlined">
	<term>Underlined</term>
	<listitem>
	  <para>
	    It is usually a good idea to underline
	    <link linkend="widget-text-field-editable"><citetitle>editable</citetitle></link>
	    text fields, since otherwise the user has no visual clue
	    about the existence of the field.
	  </para>
	</listitem>
      </varlistentry>
	
      <varlistentry id="widget-text-field-autoshift">
	<term>Auto-shift</term>
	<listitem>
	  <para>
	    If you set this property, the graffiti shift state will
	    behave "smartly", e.g. shift will be turned on
	    for new sentences.
	  </para>
	</listitem>
      </varlistentry>
      
      <varlistentry id="widget-text-field-dynamic">
	<term>Dynamic size</term>
	<listitem>
	  <para>
	    If this flag is set, <emphasis>fldHeightChangedEvent</emphasis>s
	    are generated when the number of lines needed to display
	    the contents changes. The application then needs to
	    handle this event by optionally changing the size of the
	    field.
	  </para>
	  <para>
	    This only makes sense for
	    <link linkend="widget-text-field-multi-line"><citetitle>multi-line</citetitle></link>
	    text fields.
	  </para>
	</listitem>
      </varlistentry>
      
      <varlistentry id="widget-text-field-align-right">
	<term>Right-aligned</term>
	<listitem>
	  <para>
	    Alignment of the text contents.
	  </para>
	  <para>
	    Right-aligned text fields don't accept the Tab
	    character as input.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry id="widget-text-field-scrollbar">
	<term>Scrollbar</term>
	<listitem>
	  <para>
	    Set this to have a scrollbar on the right-hand side of the
	    text field when the contents are larger than the size of
	    the widget.
	  </para>
	  <para>
	    The scrolling itself will be automatically done by the OS,
	    you don't need to do anything on your own.
	  </para>
	</listitem>
      </varlistentry>
      
      <varlistentry id="widget-text-field-pos">
      <term>X and Y</term>
      <listitem>
	<para>
	  Horizontal and vertical position relative to the parent
	  form, in pixels, counted from left to right and top to
	  bottom. Due to the size of the screen of PalmOS devices,
	  both X and Y are integer values between 0 and 159.
	</para>
      </listitem>
    </varlistentry>
      <varlistentry id="widget-text-field-auto-size">
      <term>Width and height</term>
      <listitem>
	<para>
	  Horizontal and vertical size, in pixels. Due to the size of
	  the screen of PalmOS devices, both width and height are
	  integer values between 1 and 160. 
	</para>
	<para>
	  You can also use automatic values calculated from the
	  size of the widget's contents.
	</para>
      </listitem>
    </varlistentry>
      
    </variablelist>

  </section>
  
  <section id="widget-graffiti">
    <title>Graffiti State Indicator</title>
    
      <para>
	This widget displays an icon showing the current state (like
	upper-case input, or punctuation marks) of the Graffiti input
	system. It is automatically connected to the input system, so
	you don't have to bother implementing it. Just place it on a
	form and you're set.
      </para>
    
    <variablelist>
      <varlistentry id="widget-graffiti-id">
      <term>Resource ID</term>
      <listitem>
	<para>
	  A unique string ID used for accessing the resource at
	  run-time from the program
	</para>
      </listitem>
    </varlistentry>
      <varlistentry id="widget-graffiti-pos">
      <term>X and Y</term>
      <listitem>
	<para>
	  Horizontal and vertical position relative to the parent
	  form, in pixels, counted from left to right and top to
	  bottom. Due to the size of the screen of PalmOS devices,
	  both X and Y are integer values between 0 and 159.
	</para>
      </listitem>
    </varlistentry>
    </variablelist>
  </section>
  
  <section id="widget-button">
    <title>Button</title>
    
      <para>
	A button is a (rounded) rectangular user interface element
	that emits a specific signal to the application when the user
	taps it with the stylus.
      </para>
    
    <variablelist>
      <varlistentry id="widget-button-id">
      <term>Resource ID</term>
      <listitem>
	<para>
	  A unique string ID used for accessing the resource at
	  run-time from the program
	</para>
      </listitem>
    </varlistentry>
      <varlistentry id="widget-button-usable">
      <term>Usable</term>
      <listitem>
	<para>
	  Non-usable widgets are not rendered on the screen and don't
	  receive events. You can set/unset the "usable"
	  property at run-time with the <emphasis>CtlSetUsable</emphasis>
	  function.
	</para>
      </listitem>
    </varlistentry>      

      <varlistentry id="widget-button-text-font">
      <term>Text and font</term>
      <listitem>
	<para>
	  The textual contents of the widget. It will be rendered
	  using the specified font.
	</para>
	<para>
	  Guikachu currently only supports the built-in fonts.
	</para>
      </listitem>
    </varlistentry>
      <varlistentry id="widget-button-graphical">
      <term>Bitmap/Selected Bitmap</term>
      <listitem>
	<para>
	  Select a <link linkend="resource-bitmap"><citetitle>Bitmap or Bitmap
	  Group</citetitle></link> resource to be displayed instead of the textual
	  caption.
	</para>
	<para>
	  Usually, you should specify a separate bitmap for the
	  widget's selected state, since otherwise the normal bitmap
	  is used.
	</para>
      </listitem>
    </varlistentry>

      <varlistentry id="widget-button-frame">
	<term>Frame type</term>
	<listitem>
	  <para>
	    Buttons can optionally have one of two types of frame
	    around them. It is usually a good idea to give buttons a
	    frame as this helps users distinguishing it from a simple
	    <link linkend="widget-label"><citetitle>label</citetitle></link>
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry id="widget-button-repeating">
	<term>Repeating</term>
	<listitem>
	  <para>
	    Repeating buttons emit several <emphasis>ButtonPress</emphasis>
	    signals when kept pressed by the user.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry id="widget-button-anchor-right">
      <term>Anchor right</term>
      <listitem>
	<para>
	  If the widget's size changes at run-time and this flag is
	  set, the new horizontal position is calculated to leave the
	  widget's right edge at place.
	</para>
      </listitem>
    </varlistentry>
      
      <varlistentry id="widget-button-pos">
      <term>X and Y</term>
      <listitem>
	<para>
	  Horizontal and vertical position relative to the parent
	  form, in pixels, counted from left to right and top to
	  bottom. Due to the size of the screen of PalmOS devices,
	  both X and Y are integer values between 0 and 159.
	</para>
      </listitem>
    </varlistentry>
      <varlistentry id="widget-button-auto-size">
      <term>Width and height</term>
      <listitem>
	<para>
	  Horizontal and vertical size, in pixels. Due to the size of
	  the screen of PalmOS devices, both width and height are
	  integer values between 1 and 160. 
	</para>
	<para>
	  You can also use automatic values calculated from the
	  size of the widget's contents.
	</para>
      </listitem>
    </varlistentry>
      
    </variablelist>

  </section>


  <section id="widget-checkbox">
    <title>Check box</title>
    
      <para>
	A check box contains a state icon and a text label. The state
	icon shows whether the widget is "checked", this
	state can then be handled by the application via the
	<emphasis>CtlGetValue</emphasis> function.
      </para>
    
    <variablelist>
      <varlistentry id="widget-checkbox-id">
      <term>Resource ID</term>
      <listitem>
	<para>
	  A unique string ID used for accessing the resource at
	  run-time from the program
	</para>
      </listitem>
    </varlistentry>
      <varlistentry id="widget-checkbox-usable">
      <term>Usable</term>
      <listitem>
	<para>
	  Non-usable widgets are not rendered on the screen and don't
	  receive events. You can set/unset the "usable"
	  property at run-time with the <emphasis>CtlSetUsable</emphasis>
	  function.
	</para>
      </listitem>
    </varlistentry>     

      <varlistentry id="widget-checkbox-text-font">
      <term>Text and font</term>
      <listitem>
	<para>
	  The textual contents of the widget. It will be rendered
	  using the specified font.
	</para>
	<para>
	  Guikachu currently only supports the built-in fonts.
	</para>
      </listitem>
    </varlistentry>

      <varlistentry id="widget-checkbox-toggled">
	<term>Toggled</term>
	<listitem>
	  <para>
	    Initial checked/unchecked state of the widget
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry id="widget-checkbox-group">
      <term>Group ID</term>
	<listitem>
	<para>
	  If a check box or pushbutton belongs to a group, only one
	  per group can be checked by the user. This is 
	  automatically enforced by PalmOS. Note that check boxes and
	  pushbuttons share their groups.
	</para>
	<para>
	  Set the group ID to 0 if you don't want to include it in any
	  group.
	</para>
      </listitem>
    </varlistentry>
      
      <varlistentry id="widget-checkbox-anchor-right">
      <term>Anchor right</term>
      <listitem>
	<para>
	  If the widget's size changes at run-time and this flag is
	  set, the new horizontal position is calculated to leave the
	  widget's right edge at place.
	</para>
      </listitem>
    </varlistentry>

      <varlistentry id="widget-checkbox-pos">
      <term>X and Y</term>
      <listitem>
	<para>
	  Horizontal and vertical position relative to the parent
	  form, in pixels, counted from left to right and top to
	  bottom. Due to the size of the screen of PalmOS devices,
	  both X and Y are integer values between 0 and 159.
	</para>
      </listitem>
    </varlistentry>
      <varlistentry id="widget-checkbox-auto-size">
      <term>Width and height</term>
      <listitem>
	<para>
	  Horizontal and vertical size, in pixels. Due to the size of
	  the screen of PalmOS devices, both width and height are
	  integer values between 1 and 160. 
	</para>
	<para>
	  You can also use automatic values calculated from the
	  size of the widget's contents.
	</para>
      </listitem>
    </varlistentry>
      
    </variablelist>

  </section>

  <section id="widget-pushbutton">
    <title>Pushbutton</title>
    
      <para>
	A pushbutton behaves a lot like a
	<link linkend="widget-checkbox"><citetitle>check box</citetitle></link>, except it has no
	initial state and is rendered as a rectangular
	button.
      </para>
    
    <variablelist>
      <varlistentry id="widget-pushbutton-id">
      <term>Resource ID</term>
      <listitem>
	<para>
	  A unique string ID used for accessing the resource at
	  run-time from the program
	</para>
      </listitem>
    </varlistentry>
      <varlistentry id="widget-pushbutton-usable">
      <term>Usable</term>
      <listitem>
	<para>
	  Non-usable widgets are not rendered on the screen and don't
	  receive events. You can set/unset the "usable"
	  property at run-time with the <emphasis>CtlSetUsable</emphasis>
	  function.
	</para>
      </listitem>
    </varlistentry>
      
      <varlistentry id="widget-pushbutton-text-font">
      <term>Text and font</term>
      <listitem>
	<para>
	  The textual contents of the widget. It will be rendered
	  using the specified font.
	</para>
	<para>
	  Guikachu currently only supports the built-in fonts.
	</para>
      </listitem>
    </varlistentry>
      <varlistentry id="widget-pushbutton-graphical">
      <term>Bitmap/Selected Bitmap</term>
      <listitem>
	<para>
	  Select a <link linkend="resource-bitmap"><citetitle>Bitmap or Bitmap
	  Group</citetitle></link> resource to be displayed instead of the textual
	  caption.
	</para>
	<para>
	  Usually, you should specify a separate bitmap for the
	  widget's selected state, since otherwise the normal bitmap
	  is used.
	</para>
      </listitem>
    </varlistentry>

      <varlistentry id="widget-pushbutton-group">
      <term>Group ID</term>
	<listitem>
	<para>
	  If a check box or pushbutton belongs to a group, only one
	  per group can be checked by the user. This is 
	  automatically enforced by PalmOS. Note that check boxes and
	  pushbuttons share their groups.
	</para>
	<para>
	  Set the group ID to 0 if you don't want to include it in any
	  group.
	</para>
      </listitem>
    </varlistentry>

      <varlistentry id="widget-pushbutton-pos">
      <term>X and Y</term>
      <listitem>
	<para>
	  Horizontal and vertical position relative to the parent
	  form, in pixels, counted from left to right and top to
	  bottom. Due to the size of the screen of PalmOS devices,
	  both X and Y are integer values between 0 and 159.
	</para>
      </listitem>
    </varlistentry>
      <varlistentry id="widget-pushbutton-auto-size">
      <term>Width and height</term>
      <listitem>
	<para>
	  Horizontal and vertical size, in pixels. Due to the size of
	  the screen of PalmOS devices, both width and height are
	  integer values between 1 and 160. 
	</para>
	<para>
	  You can also use automatic values calculated from the
	  size of the widget's contents.
	</para>
      </listitem>
    </varlistentry>
      
    </variablelist>

  </section>

  <section id="widget-selector-trigger">
    <title>Selector trigger</title>
    
      <para>
	Selector triggers are a lot like <link linkend="widget-button"><citetitle>buttons</citetitle></link>,
	the only difference is in the looks. The real difference is in
	intention: selector triggers should be used in cases where
	input is done by tapping the trigger, and then filling in the
	form that pops up.
      </para>
    
    <variablelist>
      <varlistentry id="widget-selector-trigger-id">
      <term>Resource ID</term>
      <listitem>
	<para>
	  A unique string ID used for accessing the resource at
	  run-time from the program
	</para>
      </listitem>
    </varlistentry>
      <varlistentry id="widget-selector-trigger-usable">
      <term>Usable</term>
      <listitem>
	<para>
	  Non-usable widgets are not rendered on the screen and don't
	  receive events. You can set/unset the "usable"
	  property at run-time with the <emphasis>CtlSetUsable</emphasis>
	  function.
	</para>
      </listitem>
    </varlistentry>

      <varlistentry id="widget-selector-trigger-text-font">
      <term>Text and font</term>
      <listitem>
	<para>
	  The textual contents of the widget. It will be rendered
	  using the specified font.
	</para>
	<para>
	  Guikachu currently only supports the built-in fonts.
	</para>
      </listitem>
    </varlistentry>
      <varlistentry id="widget-selector-trigger-graphical">
      <term>Bitmap/Selected Bitmap</term>
      <listitem>
	<para>
	  Select a <link linkend="resource-bitmap"><citetitle>Bitmap or Bitmap
	  Group</citetitle></link> resource to be displayed instead of the textual
	  caption.
	</para>
	<para>
	  Usually, you should specify a separate bitmap for the
	  widget's selected state, since otherwise the normal bitmap
	  is used.
	</para>
      </listitem>
    </varlistentry>
      <varlistentry id="widget-selector-trigger-anchor-right">
      <term>Anchor right</term>
      <listitem>
	<para>
	  If the widget's size changes at run-time and this flag is
	  set, the new horizontal position is calculated to leave the
	  widget's right edge at place.
	</para>
      </listitem>
    </varlistentry>
      
      <varlistentry id="widget-selector-trigger-pos">
      <term>X and Y</term>
      <listitem>
	<para>
	  Horizontal and vertical position relative to the parent
	  form, in pixels, counted from left to right and top to
	  bottom. Due to the size of the screen of PalmOS devices,
	  both X and Y are integer values between 0 and 159.
	</para>
      </listitem>
    </varlistentry>
      <varlistentry id="widget-selector-trigger-auto-size">
      <term>Width and height</term>
      <listitem>
	<para>
	  Horizontal and vertical size, in pixels. Due to the size of
	  the screen of PalmOS devices, both width and height are
	  integer values between 1 and 160. 
	</para>
	<para>
	  You can also use automatic values calculated from the
	  size of the widget's contents.
	</para>
      </listitem>
    </varlistentry>
    </variablelist>
  </section>
  
  <section id="widget-popup-trigger">
    <title>Popup trigger</title>
    
      <para>
	Popup triggers are usually called "drop-down lists"
	or "combo boxes" on other platforms. On tapping, the
	popup trigger displays a list of items and waits for the user
	to select a list item.
      </para>
      <para>
	The <link linkend="widget-list"><citetitle>list</citetitle></link> linked to the trigger is
	usually placed at the same spot as the trigger, with the list
	set to <link linkend="widget-list-usable"><citetitle>unusable</citetitle></link> so it isn't
	displayed until the trigger is tapped.
      </para>
    
    <variablelist>
      <varlistentry id="widget-popup-trigger-id">
      <term>Resource ID</term>
      <listitem>
	<para>
	  A unique string ID used for accessing the resource at
	  run-time from the program
	</para>
      </listitem>
    </varlistentry>
      <varlistentry id="widget-popup-trigger-usable">
      <term>Usable</term>
      <listitem>
	<para>
	  Non-usable widgets are not rendered on the screen and don't
	  receive events. You can set/unset the "usable"
	  property at run-time with the <emphasis>CtlSetUsable</emphasis>
	  function.
	</para>
      </listitem>
    </varlistentry>

      <varlistentry id="widget-popup-trigger-text-font">
      <term>Text and font</term>
      <listitem>
	<para>
	  The textual contents of the widget. It will be rendered
	  using the specified font.
	</para>
	<para>
	  Guikachu currently only supports the built-in fonts.
	</para>
      </listitem>
    </varlistentry>
      <varlistentry id="widget-popup-trigger-graphical">
      <term>Bitmap/Selected Bitmap</term>
      <listitem>
	<para>
	  Select a <link linkend="resource-bitmap"><citetitle>Bitmap or Bitmap
	  Group</citetitle></link> resource to be displayed instead of the textual
	  caption.
	</para>
	<para>
	  Usually, you should specify a separate bitmap for the
	  widget's selected state, since otherwise the normal bitmap
	  is used.
	</para>
      </listitem>
    </varlistentry>

      <varlistentry id="widget-popup-trigger-list-id">
	<term>List ID</term>
	<listitem>
	  <para>
	    The ID of the <link linkend="widget-list"><citetitle>list widget</citetitle></link> to
	    pop up when the trigger is tapped by the user.
	  </para>
	</listitem>
      </varlistentry>
      
      <varlistentry id="widget-popup-trigger-anchor-right">
      <term>Anchor right</term>
      <listitem>
	<para>
	  If the widget's size changes at run-time and this flag is
	  set, the new horizontal position is calculated to leave the
	  widget's right edge at place.
	</para>
      </listitem>
    </varlistentry>
      
      <varlistentry id="widget-popup-trigger-pos">
      <term>X and Y</term>
      <listitem>
	<para>
	  Horizontal and vertical position relative to the parent
	  form, in pixels, counted from left to right and top to
	  bottom. Due to the size of the screen of PalmOS devices,
	  both X and Y are integer values between 0 and 159.
	</para>
      </listitem>
    </varlistentry>
      <varlistentry id="widget-popup-trigger-auto-size">
      <term>Width and height</term>
      <listitem>
	<para>
	  Horizontal and vertical size, in pixels. Due to the size of
	  the screen of PalmOS devices, both width and height are
	  integer values between 1 and 160. 
	</para>
	<para>
	  You can also use automatic values calculated from the
	  size of the widget's contents.
	</para>
      </listitem>
    </varlistentry>
    </variablelist>
  </section>
  
  <section id="widget-scrollbar">
    <title>Scroll bar</title>
    
      <para>
	Scroll bars are vertical rulers displaying a user-changeable
	value in a given interval. The user can change this value by
	dragging a slider up or down.
      </para>
      <para>
	You can use the
	<emphasis>SclGetScrollBar</emphasis>/<emphasis>SclSetScrollBar</emphasis>
	functions to retrieve/modify the value and state of the
	scroll bar at run-time.
      </para>
    
    <variablelist>
      <varlistentry id="widget-scrollbar-id">
      <term>Resource ID</term>
      <listitem>
	<para>
	  A unique string ID used for accessing the resource at
	  run-time from the program
	</para>
      </listitem>
    </varlistentry>
      <varlistentry id="widget-scrollbar-usable">
      <term>Usable</term>
      <listitem>
	<para>
	  Non-usable widgets are not rendered on the screen and don't
	  receive events. You can set/unset the "usable"
	  property at run-time with the <emphasis>CtlSetUsable</emphasis>
	  function.
	</para>
      </listitem>
    </varlistentry>

      <varlistentry id="widget-scrollbar-min-max">
	<term>Value interval</term>
	<listitem>
	  <para>
	    Minimal and maximal value of the slider.
	  </para>
	  <para>
	    Due to limitations of the PalmOS platform, both the
	    minimal and the maximal value need to be integers between
	    0 and 32767 (this is enforced by the property editor in
	    Guikachu)
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry id="widget-scrollbar-value">
	<term>Initial value</term>
	<listitem>
	  <para>
	    The initial value of the scroll bar at start-up, within the
	    <link linkend="widget-scrollbar-value"><citetitle>valid interval</citetitle></link>.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry id="widget-scrollbar-page-size">
	<term>Page size</term>
	<listitem>
	  <para>
	    The amount of change when the user taps the scroll bar
	    instead of dragging the slider or tapping one of the
	    arrows at the end of the bar.
	  </para>
	</listitem>
      </varlistentry>
      
      <varlistentry id="widget-scrollbar-pos">
      <term>X and Y</term>
      <listitem>
	<para>
	  Horizontal and vertical position relative to the parent
	  form, in pixels, counted from left to right and top to
	  bottom. Due to the size of the screen of PalmOS devices,
	  both X and Y are integer values between 0 and 159.
	</para>
      </listitem>
    </varlistentry>
      <varlistentry id="widget-scrollbar-auto-size">
      <term>Width and height</term>
      <listitem>
	<para>
	  Horizontal and vertical size, in pixels. Due to the size of
	  the screen of PalmOS devices, both width and height are
	  integer values between 1 and 160. 
	</para>
	<para>
	  You can also use automatic values calculated from the
	  size of the widget's contents.
	</para>
      </listitem>
    </varlistentry>
    </variablelist>
  </section>
  
  <section id="widget-list">
    <title>List</title>
    
      <para>
	This widget is a list of one-line text items. Selecting a list
	item emits a <emphasis>lstSelectEvent</emphasis>. You can then use
	<emphasis>LstGetSelection</emphasis> in the event handler to get the
	currently selected item.
      </para>
      <para>
	Lists are also used by <link linkend="widget-popup-trigger"><citetitle>popup
	triggers</citetitle></link>: the list linked to the trigger is shown when
	the trigger is tapped by the user.
      </para>
    
    <variablelist>
      <varlistentry id="widget-list-id">
      <term>Resource ID</term>
      <listitem>
	<para>
	  A unique string ID used for accessing the resource at
	  run-time from the program
	</para>
      </listitem>
    </varlistentry>
      <varlistentry id="widget-list-usable">
      <term>Usable</term>
      <listitem>
	<para>
	  Non-usable widgets are not rendered on the screen and don't
	  receive events. You can set/unset the "usable"
	  property at run-time with the <emphasis>CtlSetUsable</emphasis>
	  function.
	</para>
      </listitem>
    </varlistentry>

      <varlistentry id="widget-list-visible-items">
	<term>Visible items</term>
	<listitem>
	  <para>
	    Number of items displayed at a time. There needs to be at
	    least that many items in the list, or undefined things may
	    happen (including the possibility of the PalmOS device
	    freezing).
	  </para>
	  <para>
	    If there are more items than displayed at a time, the user
	    is able to scroll through items.
	  </para>
	</listitem>
      </varlistentry>
      
      <varlistentry id="widget-list-font">
	<term>Font</term>
	<listitem>
	  <para>
	    The font used to display the list items
	  </para>
	  <para>	    
	    Guikachu currently only supports the three default built-in
	    fonts: #0 is the "normal", #1 is the "bold" and
	    #2 is the "large" font.
	  </para>
	</listitem>
      </varlistentry>
      
      <varlistentry id="widget-list-pos">
      <term>X and Y</term>
      <listitem>
	<para>
	  Horizontal and vertical position relative to the parent
	  form, in pixels, counted from left to right and top to
	  bottom. Due to the size of the screen of PalmOS devices,
	  both X and Y are integer values between 0 and 159.
	</para>
      </listitem>
    </varlistentry>
      <varlistentry id="widget-list-width">
	<term>Width</term>
	<listitem>
	  <para>
	    Horizontal size, in pixels. Due to the size of
	    the screen of PalmOS devices, this is an integer value
	    between 1 and 160.
	  </para>
	  <para>
	    You can also use an automatic value calculated from the
	    width of the first list item.
	  </para>
	  <para>
	    The height of the widget will be automatically calculated
	    from the
	    <link linkend="widget-list-visible-items"><citetitle>number of visible
	    items</citetitle></link> and the <link linkend="widget-list-font"><citetitle>font</citetitle></link> used.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>
  </section>
  
  <section id="widget-table">
    <title>Table</title>
    
      <para>
	Use tables to show multi-column data. The PalmOS API makes it
	very easy to bind table cells to database fields and other
	persistent data.
      </para>
      <para>
	Most of the behavior of tables are defined at run-time
	instead of the resource file. Refer to the PalmOS API
	documentation for further information on the related
	library functions.
      </para>
    
    <variablelist>
      <varlistentry id="widget-table-id">
      <term>Resource ID</term>
      <listitem>
	<para>
	  A unique string ID used for accessing the resource at
	  run-time from the program
	</para>
      </listitem>
    </varlistentry>

      <varlistentry id="widget-table-rows">
	<term>Number of rows</term>
	<listitem>
	  <para>
	    The number of rows visible. The height of the rows will be
	    calculated at run-time based on cell type and content.	   
	  </para>
	  <para>
	    The Form Editor displays rows at the default height of
	    11 pixels.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry id="widget-table-columns">
	<term>Columns</term>
	<listitem>
	  <para>
	    Only the number of columns, and each column's width is
	    stored in the resource file. All other aspects of columns
	    (most notably, their content type) is set at run-time.
	  </para>
	</listitem>
      </varlistentry>
      
      <varlistentry id="widget-table-pos">
      <term>X and Y</term>
      <listitem>
	<para>
	  Horizontal and vertical position relative to the parent
	  form, in pixels, counted from left to right and top to
	  bottom. Due to the size of the screen of PalmOS devices,
	  both X and Y are integer values between 0 and 159.
	</para>
      </listitem>
    </varlistentry>
      
      <varlistentry id="widget-table-size">
	<term>Width and height</term>
	<listitem>
	  <para>
	    Although PilRC allows you to include height and width
	    information for tables, these values are not used, and an
	    automatic size based on
	    <link linkend="widget-table-columns"><citetitle>column width</citetitle></link>
	    and <link linkend="widget-table-rows"><citetitle>number of rows</citetitle></link>. Due
	    to this, Guikachu doesn't confuse the user with bogus size
	    settings. 
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>
  </section>

  <section id="widget-formbitmap">
    <title>Bitmap widget</title>
    
      <para>
      </para>
    
    <variablelist>
      <varlistentry id="widget-formbitmap-id">
      <term>Resource ID</term>
      <listitem>
	<para>
	  A unique string ID used for accessing the resource at
	  run-time from the program
	</para>
      </listitem>
    </varlistentry>
      <varlistentry id="widget-formbitmap-usable">
      <term>Usable</term>
      <listitem>
	<para>
	  Non-usable widgets are not rendered on the screen and don't
	  receive events. You can set/unset the "usable"
	  property at run-time with the <emphasis>CtlSetUsable</emphasis>
	  function.
	</para>
      </listitem>
    </varlistentry>
      <varlistentry id="widget-formbitmap-bitmapref">
	<term>Bitmap ID</term>
	<listitem>
	  <para>
	    ID of the 
	    <link linkend="res-bitmap"><citetitle>Bitmap/Bitmap Group</citetitle></link>
	    resource to display.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry id="widget-formbitmap-pos">
      <term>X and Y</term>
      <listitem>
	<para>
	  Horizontal and vertical position relative to the parent
	  form, in pixels, counted from left to right and top to
	  bottom. Due to the size of the screen of PalmOS devices,
	  both X and Y are integer values between 0 and 159.
	</para>
      </listitem>
    </varlistentry>
    </variablelist>
  </section>
  
  <section id="widget-gadget">
    <title>Gadget</title>
    
      <para>
	Gadgets are placeholders for widgets implemented by the app
	author. The application is responsible for rendering the
	widget and maintaining any associated state data.
      </para>
    
    <variablelist>
      <varlistentry id="widget-gadget-id">
      <term>Resource ID</term>
      <listitem>
	<para>
	  A unique string ID used for accessing the resource at
	  run-time from the program
	</para>
      </listitem>
    </varlistentry>
      <varlistentry id="widget-gadget-usable">
      <term>Usable</term>
      <listitem>
	<para>
	  Non-usable widgets are not rendered on the screen and don't
	  receive events. You can set/unset the "usable"
	  property at run-time with the <emphasis>CtlSetUsable</emphasis>
	  function.
	</para>
      </listitem>
    </varlistentry>      
     
      <varlistentry id="widget-gadget-pos">
      <term>X and Y</term>
      <listitem>
	<para>
	  Horizontal and vertical position relative to the parent
	  form, in pixels, counted from left to right and top to
	  bottom. Due to the size of the screen of PalmOS devices,
	  both X and Y are integer values between 0 and 159.
	</para>
      </listitem>
    </varlistentry>
      <varlistentry id="widget-gadget-size">
      <term>Width and height</term>
      <listitem>
	<para>
	  Horizontal and vertical size, in pixels. Due to the size of
	  the screen of PalmOS devices, both width and height are
	  integer values between 1 and 160. 
	</para>
      </listitem>
    </varlistentry>
      
    </variablelist>

  </section>

</section>
  
</article>
