Gergő Érdi

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. Guikachu is a PalmOS resource editor that runs in the UNIX environment, using the GNOME desktop framework. At the time of writing this manual, Guikachu is the only PalmOS resource editor application for UNIX systems. If you've used Glade, a user interface editor for GNOME, the interface of Guikachu will look familiar. Unlike most of the applications available for Windows and MacOS, Guikachu is Free Software 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 GNU GPL for the specific license terms. You can find news about the project and the latest releases of the application at the Guikachu web site.

There are several ways of starting up Guikachu: Click on the Guikachu icon in the Development category of the GNOME Panel menu to launch Guikachu with an empty document. Double-click on an existing Guikachu document in Nautilus to start editing the selected document with Guikachu. 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. You can also open remote URI's from the command line, as in the following example: The last edited file is remembered, and it is automatically loaded when the session manager restarts Guikachu. Refer to the GNOME documentation on setting up the session manager with GNOME. Regardless of how you start Guikachu, the application starts with the main window displayed.

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. 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. Compiling an RCP file into PalmOS machine code is done as shown in the following example (compiling my-app-1.rcp): pilrc -H my-app-1.rcp.h my-app-1.rcp 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. 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: /* pilrc generated file. Do not edit! */ #define HelpAbout 9973 #define FileSave 9974 #define FileOpen 9975 #define FileDanger 9976 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.

The main window shows the contents of the current project and allows you to do I/O operations and edit/add/remove resources.

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.

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. Choose "PilRC document" in the File Type dropdown list, and select an RCP file from the file list to import an RCP file. Guikachu remembers the last couple of files opened, and you can quickly access them from the bottom of the File menu. 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. Use the New command from the File menu or the tool bar to start a new project from scratch.

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.

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.

The Edit menu of the main window contains commands for manipulating the clipboard and using the undo system. 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. Note: Due to the way clipboards in the X Window System work, the contents of the clipboard are lost when you quit Guikachu. 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. 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.

Click on Preferences in the Edit menu to display the dialog box where you can tune certain aspects of Guikachu to your liking.

Currently, there are preference settings only for the Form Editor. 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. 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.

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 menu editor and the form editor (see their description later), these property editors share a common set of controls. 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).

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. Some resource windows are broken into multiple pages of property editors. Click on the tabs at the top of the window to change pages.

There are three types of textual properties in Guikachu: resource ID's, single-line small strings and multi-line, long texts.

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.

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.

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. For user-visible strings (i.e. not ID's), you can use the \ character to include "escape sequences". The two most important notions are \nnn where nnn is an octal number, and \xnn, where nn 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, \r is not yet supported by Guikachu.

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.

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. 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.

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.

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. The first time you change an automatic value to a manual one, the manual value is initialized with the currently calculated value.

Some properties can only have values from a fixed set. Clicking on the current value pops up a list of options.

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. The dialog editor also has a special Default button. Press this to mark the currently selected item as the default response.

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.

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. 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. Sub-menus are only part of the user interface, they do not emit events themselves. Thus, sub-menus only have a label and don't have an ID.

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. 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. 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. 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. Sub-menus and menu items can be deleted with the Remove button. Removing a sub-menu deletes all its children as well.

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. 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.

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 Bitmap widget, or using them as custom buttons, pushbuttons, selector triggers, or popup triggers.

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.

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. 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.

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.

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.

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. 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.

Each item of the list also contains an icon showing the type of the widget. The selection is synchronized between the widget list and the preview tab. Depending on the screen capabilities of the target machine, the form preview will be displayed in either color or greyscale mode. In greyscale mode, color bitmaps are shown in greyscale, and widgets are drawn using the foreground and background colors set in the Preferences dialog.

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.

Widgets available on the widget palette, from left to right and top to bottom, are: Label, Text Field, Graffiti state indicator Button, Pushbutton, Selector trigger Check box, Popup trigger, List Scroll bar, Table, Bitmap Gadget (custom widget) 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 "selection" tool. 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.

Widget operations such as moving or deleting are always done on the current widget selection. Selecting a widget also opens its editor window. 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. 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.

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.

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.

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. 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.

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 property editor windows.

You can move widgets either by changing their X and Y 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.

Some widgets' dimensions are determined by their content: for example, a label's size will always be determined by the text it contains. The size of widgets like buttons, on the other hand, can be changed to make a widget smaller or larger than their automatic dimensions. 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.

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.

Clicking on a widget not only changes the selection: it also opens the editor window for the widget. Widget editors are just like resource windows, and contain the same types of property editors. 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.

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. 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.

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. You can edit these by double-clicking on the root element of the resource tree (the one that initially reads Application). Icon caption The string that will be displayed in the application launcher and the various statistics windows (e.g. the memory usage list) Version The string displayed in the Version view of the Info window Vendor ID The four character long, case-sensitive vendor ID's should be globally unique -- contact PalmOS.com to register your vendor ID. Target machine 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. You can either choose from a list of devices with pre-configured values, or choose "Custom machine" to create a custom definition.

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. Note that you can store multiple fragments in a single Guikachu document, to make things more organized. Resource ID 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.

String resources are used to store static, user-visible strings, separated from the code. To access them from your application, use the following code: Char *msg = MemHandleLock (DmGetResource (strRsc, string_id)); /* Do something with the string */ MemPtrUnlock (msg); Resource ID A unique string ID used for accessing the resource at run-time from the program String The contents of the string

String lists contain several, usually related, strings. The following code shows how you can access the items of a string list from your application: 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)) << 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. */ Resource ID A unique string ID used for accessing the resource at run-time from the program Prefix This string is prepended to every list item when items are retrieved by the SysStringByIndex function.

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 string resource that is used in the pop-up help. Resource ID A unique string ID used for accessing the resource at run-time from the program Title The title of the dialog, displayed in the title bar Type Specifies the icon shown in the dialog. Please see the PalmOS Reference for a detailed description on when to use which mode Help ID The (optional) resource ID of a string that describes the usage of the dialog. If specified, the title bar of the dialog will include a ? button to display the help. Text 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. Buttons 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 FrmAlert will be the index of the button pressed (starting at 0). If the user exits the dialog by switching to another application, FrmAlert will return with the default button's index.

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. 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. The actual implementation of the menu items are done by looking at the itemID in the menuEvent handler of the form owning the menu bar. Resource ID A unique string ID used for accessing the resource at run-time from the program

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. 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. 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. Resource ID A unique string ID used for accessing the resource at run-time from the program Type 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.

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. You can also use a form as a modal dialog via the FrmDoDialog function. This works just like FrmAlert 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 default button's ID if the form is closed by switching to another application). Resource ID A unique string ID used for accessing the resource at run-time from the program Title The title of the form, shown on the top of it. Its actual rendering is dependent on the form's modalness. 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. Help ID If this is set to a valid string resource, and the form is modal, a help button is displayed in the title area of the form, which, when clicked, pops up a dialog containing the help text. Menu ID The ID of a menu resource associated with the form. Modal 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. Dialog resources provide an easy-to-use mechanism for displaying simple modal forms. Frame 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. Save behind 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. Default button It is possible to use a form as a custom modal dialog via the FrmCustomAlert 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. X and Y 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. Width and height 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.

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 events. See the PalmOS documentation and the example application included with Guikachu for more information on handling widget events.

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 text field. Resource ID A unique string ID used for accessing the resource at run-time from the program Usable 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 CtlSetUsable function. Text and font The textual contents of the widget. It will be rendered using the specified font. Guikachu currently only supports the built-in fonts. X and Y 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.

A text field contains text that is changeable at run-time, either by the application or by the user. There are several ways to set/get the currently displayed text of a text field, see the PalmOS SDK for details. Resource ID A unique string ID used for accessing the resource at run-time from the program Usable 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 CtlSetUsable function. Font The font used to display the contents of the text field Guikachu currently only supports the three default built-in fonts: #0 is the "normal", #1 is the "bold" and #2 is the "large" font. Editable Controls whether the user is able to change the field's contents. Multi-line Multi-line text fields automatically wrap input at the end of visible lines. They also accept newline and tab as input. Numeric-only Set this property to restrict input by the user to numbers only. Since it only controls user input, it makes sense only for editable text fields. Maximum length 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). Underlined It is usually a good idea to underline editable text fields, since otherwise the user has no visual clue about the existence of the field. Auto-shift If you set this property, the graffiti shift state will behave "smartly", e.g. shift will be turned on for new sentences. Dynamic size If this flag is set, fldHeightChangedEvents 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. This only makes sense for multi-line text fields. Right-aligned Alignment of the text contents. Right-aligned text fields don't accept the Tab character as input. Scrollbar 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. The scrolling itself will be automatically done by the OS, you don't need to do anything on your own. X and Y 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. Width and height 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. You can also use automatic values calculated from the size of the widget's contents.

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. Resource ID A unique string ID used for accessing the resource at run-time from the program X and Y 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.

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. Resource ID A unique string ID used for accessing the resource at run-time from the program Usable 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 CtlSetUsable function. Text and font The textual contents of the widget. It will be rendered using the specified font. Guikachu currently only supports the built-in fonts. Bitmap/Selected Bitmap Select a Bitmap or Bitmap Group resource to be displayed instead of the textual caption. Usually, you should specify a separate bitmap for the widget's selected state, since otherwise the normal bitmap is used. Frame type 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 label Repeating Repeating buttons emit several ButtonPress signals when kept pressed by the user. Anchor right 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. X and Y 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. Width and height 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. You can also use automatic values calculated from the size of the widget's contents.

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 CtlGetValue function. Resource ID A unique string ID used for accessing the resource at run-time from the program Usable 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 CtlSetUsable function. Text and font The textual contents of the widget. It will be rendered using the specified font. Guikachu currently only supports the built-in fonts. Toggled Initial checked/unchecked state of the widget Group ID 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. Set the group ID to 0 if you don't want to include it in any group. Anchor right 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. X and Y 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. Width and height 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. You can also use automatic values calculated from the size of the widget's contents.

A pushbutton behaves a lot like a check box, except it has no initial state and is rendered as a rectangular button. Resource ID A unique string ID used for accessing the resource at run-time from the program Usable 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 CtlSetUsable function. Text and font The textual contents of the widget. It will be rendered using the specified font. Guikachu currently only supports the built-in fonts. Bitmap/Selected Bitmap Select a Bitmap or Bitmap Group resource to be displayed instead of the textual caption. Usually, you should specify a separate bitmap for the widget's selected state, since otherwise the normal bitmap is used. Group ID 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. Set the group ID to 0 if you don't want to include it in any group. X and Y 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. Width and height 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. You can also use automatic values calculated from the size of the widget's contents.

Selector triggers are a lot like buttons, 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. Resource ID A unique string ID used for accessing the resource at run-time from the program Usable 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 CtlSetUsable function. Text and font The textual contents of the widget. It will be rendered using the specified font. Guikachu currently only supports the built-in fonts. Bitmap/Selected Bitmap Select a Bitmap or Bitmap Group resource to be displayed instead of the textual caption. Usually, you should specify a separate bitmap for the widget's selected state, since otherwise the normal bitmap is used. Anchor right 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. X and Y 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. Width and height 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. You can also use automatic values calculated from the size of the widget's contents.

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. The list linked to the trigger is usually placed at the same spot as the trigger, with the list set to unusable so it isn't displayed until the trigger is tapped. Resource ID A unique string ID used for accessing the resource at run-time from the program Usable 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 CtlSetUsable function. Text and font The textual contents of the widget. It will be rendered using the specified font. Guikachu currently only supports the built-in fonts. Bitmap/Selected Bitmap Select a Bitmap or Bitmap Group resource to be displayed instead of the textual caption. Usually, you should specify a separate bitmap for the widget's selected state, since otherwise the normal bitmap is used. List ID The ID of the list widget to pop up when the trigger is tapped by the user. Anchor right 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. X and Y 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. Width and height 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. You can also use automatic values calculated from the size of the widget's contents.

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. You can use the SclGetScrollBar/SclSetScrollBar functions to retrieve/modify the value and state of the scroll bar at run-time. Resource ID A unique string ID used for accessing the resource at run-time from the program Usable 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 CtlSetUsable function. Value interval Minimal and maximal value of the slider. 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) Initial value The initial value of the scroll bar at start-up, within the valid interval. Page size 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. X and Y 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. Width and height 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. You can also use automatic values calculated from the size of the widget's contents.

This widget is a list of one-line text items. Selecting a list item emits a lstSelectEvent. You can then use LstGetSelection in the event handler to get the currently selected item. Lists are also used by popup triggers: the list linked to the trigger is shown when the trigger is tapped by the user. Resource ID A unique string ID used for accessing the resource at run-time from the program Usable 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 CtlSetUsable function. Visible items 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). If there are more items than displayed at a time, the user is able to scroll through items. Font The font used to display the list items Guikachu currently only supports the three default built-in fonts: #0 is the "normal", #1 is the "bold" and #2 is the "large" font. X and Y 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. Width Horizontal size, in pixels. Due to the size of the screen of PalmOS devices, this is an integer value between 1 and 160. You can also use an automatic value calculated from the width of the first list item. The height of the widget will be automatically calculated from the number of visible items and the font used.

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. 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. Resource ID A unique string ID used for accessing the resource at run-time from the program Number of rows The number of rows visible. The height of the rows will be calculated at run-time based on cell type and content. The Form Editor displays rows at the default height of 11 pixels. Columns 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. X and Y 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. Width and height Although PilRC allows you to include height and width information for tables, these values are not used, and an automatic size based on column width and number of rows. Due to this, Guikachu doesn't confuse the user with bogus size settings.

Resource ID A unique string ID used for accessing the resource at run-time from the program Usable 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 CtlSetUsable function. Bitmap ID ID of the Bitmap/Bitmap Group resource to display. X and Y 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.

Gadgets are placeholders for widgets implemented by the app author. The application is responsible for rendering the widget and maintaining any associated state data. Resource ID A unique string ID used for accessing the resource at run-time from the program Usable 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 CtlSetUsable function. X and Y 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. Width and height 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.