CControls and CEditor
Introduction
Ever thought it is impossible to create real palm pilot applications using PocketC?
CControls is a function library used to develop graphic front ends on your palm pilot with PocketC, offering all GUI controls commonly known on the pilot platform - and even more.
The library comes bundled with a WYSIWYG-editor with which you're able to design directly on the palm pilot.
Please read the "Features" sections to get an idea what CControls and CEditor offer you.
|
|
|
Installation
The package contains the following files:
Please install the PRC- and PDB-files on your palm pilot using the "install" function of the pilot desktop.
The function code for CControls (three source memos) is stored in the library database. To be able to use CControls in your own code, you first have to call CEdtor and extract this code by executing "Install library" under the "Form"-menu.
After installation you will find three new memos:
/$ Ccontrols.c
/$ Ccontrols1.c
/$ Ccontrols2.c
These three source code files will be included every time you generate code for forms using CEditor. CEditor will automatically check if the libray is missing and re-extract it when generating code.
If you‘re coding your own applications without using CEditor, please take care to include the library code (look at the CControls code example).
Important: CControls and CEditor only work when PocketC (version 3.04 or higher) is installed on you palm pilot. PocketC is not included in this package.
Features
CControl features
CControls GUI controls
Currently, CControls supports the following controls:
CEditor features
CControl Usage
It is very simple to use CControls in your own PocketC source code:
Always remember:
If you want to learn more about the usage of CControls in your own code, please refer to the sample code.
Another quick approach is to use CEditor to design your GUI front end, let it generate the PocketC code for you and fill the (empty) event functions with your own actions.
CControl code example
// CControls example.c initcontrols(){ drawscreen(){ dialog(){ |
createDB() {int i,r; pointer p; p=malloc(3); settype(p,3,'s'); if (!dbcreate("CTestDB")){ alert("\nUnable to create CTestDB."); return;} for(i=0;i<10;i++){ for(r=0;r<3;r++){ p[r]="DB "+(i+1)+"/"+(r+1); } dbrec(-1); dbwritex(p,"szszsz");} } initDB(){ // actions on controlevents: onlabel1(){ onimage1(){ onswitch1(){ oncheckbox1(){ onmenu(string s){ main(){ |
CControl functions reference
Creation functions
Cedit(x,y,w,l,s,a) |
||
x |
x-position |
Creates a new edit field at the given position with the given style. Edit fields prompt for input via dialog when clicked. |
Clabel(x,y,w,l,s,a) |
||
x |
x-position |
Creates a new label field at the given position with the given style. Label fields fire events when clicked, so that they can be linked to an action if necessary. |
Clistbox(x,y,w,h) |
||
x |
x-position |
Creates a new listbox at the given position with the given style. Listboxes can be filled with items using Cadditem. To access certain items you can use Csetcursel and Cgetcontent. |
Cdropdown(x,y,w,h) |
||
x |
x-position |
Creates a new dropdown at the given position with the given style. Dropdowns can be filled with items using Cadditem. To access certain items you can use Csetcursel and Cgetcontent. |
Cpopup(x,y,w,h) |
||
x |
x-position |
Creates a new Popup at the given position with the given style. Popups can be filled with items using Cadditem. To access certain items you can use Csetcursel and Cgetcontent.Popups are not triggered by an event in the main event-handler, but by an event-action of another control. |
Cmenu(x,w,wt) |
||
x |
x-position |
Creates a new menu at the given position with the given style. Menus can be filled with item using Cadditem. To access certain items you can use Csetcursel and Cgetcontent. Menus can be added to the main menu bar using Caddmenu. |
Cmenubar() |
||
|
|
Creates the main menubar at the given position with the given style. Menus are added using Caddmenu. You can only define one menubar. |
Cbutton(x,y,w,h,l,b) |
||
x |
x-position |
Creates a new button at the given position with the given style. Buttons are labeled with text using Csetcontent. |
Cimage(x,y,w,h) |
||
x |
x-position |
Creates a new clickable image at the given position with the given style. The image shown by the control is defined by using Csetcontent with the picture resource as string parameter. Please take care to use the same width and height as the picture when defining the Cimage control. |
Cradio(x,y,w,h) |
||
x |
x-position |
Creates a new radio control at the given position with the given style. Radios can be filled with items using Cadditem. To access certain items you can use Csetcursel and Cgetcontent. |
Cswitch(x,y,w,h,l,b) |
||
x |
x-position |
Creates a new switch control at the given position with the given style. To access the state of the control you can use Csetstate and Cgetstate. |
Ccheckbox(x,y,w) |
||
x |
x-position |
Creates a new checkbox at the given position with the given style. To access the state of the control you can use Csetstate and Cgetstate. |
Ctable(x,y,w,h,r) |
||
x |
x-position |
Creates a new table at the given position with the given style. Tables can be filled with items using Cadditem (to add a new line and the first field item) in combination with Csetfield.(to fill any field items) To access certain items you can use Cgetfield (or Cgetcontent for the first field item). |
CtableDB(x,y,w,h,r,pDB,sF) |
||
x |
x-position |
Creates a new table at the given position with the given style. This kind of table is not filled using Cadditem but by directly accessing a PcoketC database using a database handle. |
Cframe(x,y,w,h) |
||
x |
x-position |
Creates a new dialog frame at the given position with the given style. In order to place controls on the dialog correctly you have to create the frame as the first control (otherwise it would overlap other controls). |
Cdestroy(Ch) |
||
Ch |
handle of control |
Destroys a control and frees the memory which was allocated for the control (and ist items). |
Drawing functions
Cdraw(Ch) |
||
Ch |
handle of control |
Draws (or re-draws) a control. to be used with: |
Cerase(Ch) |
||
Ch |
handle of control |
Erases a control from the screen (without destroying it). The control can be re-drawn using Cdraw. to be used with: |
Chide(Ch) |
||
Ch |
handle of control |
Hides a control. It can be show again using Cshow. to be used with: |
Cshow(Ch) |
||
Ch |
handle of control |
Shows a control which was hidden using Chide. to be used with: |
Cdeactivate(Ch) |
||
Ch |
handle of control |
Deactivates the functionality of the control (without hiding it). Some controls (e.g. buttons) change their appearance when deactivated. to be used with: |
Cactivate(Ch) |
||
Ch |
handle of control |
Re-activates a control which was deactivated using Cdeactivate. to be used with: |
Access functions
Csetrow(Ch,r,w,a) |
||
Ch |
handle of control |
Determines the layout of table rows. Please keep in mind that row contents are NOT automatically limited by row widths. That means that if row contents are too long this will result in "jerky" table layouts. to be used with: |
Csetstate(Ch,s) |
||
Ch |
handle of control |
Sets the state of the control. to be used with: |
Cgetstate(Ch) |
||
Ch |
handle of control |
Gets the state of the control. Returns 0 or 1. to be used with: |
Csetcursel(Ch,i) |
||
Ch |
handle of control |
Sets the selected item. The first item has an index of 0. By giving an index value of -1 no item is selcted. to be used with: |
Cgetcursel(Ch) |
||
Ch |
handle of control |
Gets the index of the currently selected item. The first item has the index 0. Returns -1 if no item is selected. to be used with: |
Csettopic(Ch,s) |
||
Ch |
handle of control |
Sets the topic text of the control. For menus this is the text shown in the menubar, for edit fields this is the text shown at the top of the dialog prompting when the control is clicked for new input (if no topic is set, the current content of the control will be displayed instead). to be used with: |
Cgettopic(Ch) |
||
Ch |
handle of control |
Gets the topic text of the controls. Returns a string value. to be used with: |
Csetfield(Ch,r,s) |
||
Ch |
handle of control |
Sets the content of a table field. The first field has the index number 0. to be used with: |
Cgetfield(Ch,r) |
||
Ch |
handle of control |
Gets the content of a table field. Returns a string vale. The first field has the index number 0. to be used with: |
Csetcontent(Ch,s) |
||
Ch |
handle of control |
Sets the content of the control. Please keep in mind that the length of the content strings is not controlled by the control automatically, so that long strings can result in "jerky" control layouts. to be used with: |
Cgetcontent(Ch) |
||
Ch |
handle of control |
Gets the current content of the control. Returns a string value. to be used with: |
Csetsize(Ch,n) |
||
Ch |
handle of control |
Allocates the memory for a certain number of items for the control. to be used with: |
Cadditem(Ch,s) |
||
Ch |
handle of control |
Adds a new item to the control. Items will be added at the end of the item list. Automatically increaeses the allocated memory by one if the pre-allocated memory (by using Csetsize) is not sufficient. to be used with: |
Cremoveitem(Ch) |
||
Ch |
handle of control |
Removes an item. To select a certain item, please use Csetcursel. to be used with: |
Caddmenu(Ch,Cm) |
||
Ch |
handle of control |
Adds a menu to the main menubar. Please keep in mind that it is not possible to change the order of existing menus, so you have to add them in the right order when calling Caddmenu. There is no command to remove menus. If you want to do this, please use Cdestroy for all menus and the menubar and then re-define them. to be used with: |
Event functions
Cevent(Ch,e) |
||
Ch |
handle of control |
Checks if the given control was activated. The event e is trapped by the PocketC event(1) function. To survey all GUI elements, you have to use a message loop which catches an event and then performs Cevent for all controls (please examine the example code for more information). to be used with: |
|
|
|
Cpopupevent(Ch) |
||
Ch |
handle of control |
Opens the popup list and checks if an item was selected by the user. to be used with: |
CEditor Usage
To produce an automatically generated PocketC application you have to perform the following steps:
CEditor generates the following code-memos for you:
CEditor functions
Screen buttons
|
|
|
Ref: refresh the screen (sometimes necessary to avoid "junkiness")
New: create a new control (will be followed by the property dialog)
M: move controls
S: change the size of controls
E: edit controls (choose one to get the property dialog)
T: test controls (to check all functions of your GUI)
D: delete controls
To access controls, which are normally hidden (like popups and menus) you can use special menu commands.
Form menu
Install CControls: generates three code-memos with the CControls function library
Generate code: generates the code-memos for your current form
New form: create a new empty form
Load form: loads a formerly saved form-project
Save form: saves the current form in a form-project
Delete form: deletes a formerly saved form-project
Edit menu
New control: inserts a new control into your form
Refresh screen: redraws the form (sometimes necessary)
Edit popup: lets you choose a popup-control for editing
Edit menu: lets you choose a menu for editing
Edit form: go back to form after editing popups or menus
Control properties (example)
All properties of the supported controls can be modified in the corresponding control property dialogs. Here you can find the same attributes which are used when modifying controls with the CControls library functions. Controls whch support the "Cadditem"-function have additional "item"-buttons, tables have an additional dropdown to choose the row to be modified by the current "row"-attributes.
Please refer to the CControls function reference to get more descriptions on the controls attributes.
The "name"-attribute determines the name of Chandle-type variable to be used for the control when generating the code-memos.
Aknowledgements and legal stuff
Copyright 1999 M. Schlesinger Consulting. All rights reserved.
CControls and CEditor can be used for free. I am a freelancing consultant and these programs are part of my "active advertising".
The only "price" for the usage of CControls is that you may mail me a copy of an interesting application which you have programmed using CControls (it would be great to see what can be done with PocketC and CControls).
This software is provided as is, with no guarantee of fitness for any particular task. The user assumes all responsibility for its use.
If you have any comments please feel free to contact me:
mail@mscon.de / www.mscon.de