developer's mag
main page
sections
part 1
part 2
part 3
part 4
part 5
part 6
part 7
part 8
part 9
2 - Operating System API
2.01 - I have an error code - now what do I do?2.02 - How can I tell where the pen is pressing onscreen?
2.03 - What kind of drawing primitives are available?
2.04 - What about pixel drawing?
2.05 - What about other drawing functions?
2.06 - Where are the img_* functions found?
2.07 - In objects like CWindow, CButton and CLabel, the label is not stored in the object, but only a pointer. Why is that?
2.08 - How do I make a button pop up?
2.09 - My custom buttons with white imaging appear transparent - why?
2.10 - Can I tell if I am in the simulator or on the ebm itself in my program?
2.11 - How can I do a progress bar while I perform an action?
2.12 - How can I call a dialog?
2.13 - Which is best, GUI_EventLoop() or Show()?
2.14 - How do I use a bitmap as a background in my program?
2.15 - Is this the only way?
2.16 - How to I prompt the user when closing the program?
2.17 - OK, what's a magic number?
2.18 - The first entry in the Default FONTGROUP doesn't make any sense - why?
2.19 - Some FONTGROUP entries are zero - why?
2.20 - Who is responsible for handling fonts - the operating system or the programmer?
2.21 - Are there any plans for Franklin to provide additional fonts or font groups?
2.22 - Where can I get more information on creating fonts?
2.01 - I have an error code - now what do I do?
Weep. Seriously, though, the function GUI_SystemErrorMsg() converts an error code into an error message.
2.02 - How can I tell where the pen is pressing onscreen?
The MSG_PEN_DOWN and MSG_PEN_UP events have the x and y coordinates packed in their data values, with x the high word, and y the low word. To unpack them, use this code (which preserves the signs):
int x=data<<16;
int y=((short)data)&0xFFFF;
2.03 - What kind of drawing primitives are available?
You can draw lines (DrawLine), rectangles (DrawRect), filled rectangles (DrawRectFilled) and copy parts or the whole of a bitmap (DrawImage)
2.04 - What about pixel drawing?
There isn't a call for it, but two possibilities exist; 1) draw a line of 1 pixel in size 2) use a lower level routine. If you go the low-level route, use the function imgPixelSetColor() in image.c and remember to reverse colors (dark to light, and vice versa)..
2.05 - What about other drawing functions?
These can be synthesized from line drawing and pixel drawing. Check the Internet for source code.
2.06 - Where are the img_* functions found?
gui_types.h
2.07 - In objects like CWindow, CButton and CLabel, the label is not stored in the object, but only a pointer. Why is that?
Space savings are a real issue on a small handheld device. Imagine the alternative: you create a window with the caption 'My Window", and now two copies of the string exist - the original string in your code, and the window's copy. Do this for enough objects, and you use up a lot of memory. Since many initialization strings are static (like many window captions), this can be a real space savings. One disadvantage of this scheme is that the pointer must be valid for the lifetime of the object. If you set the name of a window in a subroutine using local variables, for instance, weird things happen later on (speaking from experience).
2.08 - How do I make a button pop up?
One way is the call SetDownStatus(false). You may need to update the display for the effect to show, meaning a call to GUI_UpdateNow() afterwards.
2.09 - My custom buttons with white imaging appear transparent - why?
White is considered the transparent color for button images - use near white (COLOR_GRAY93) to get an opaque white on buttons.
2.10 - Can I tell if I am in the simulator or on the ebm itself in my program?
Use hostIO_is_simulator(). The flag result tells you if you in the simulator (true) or on a real live ebm (false).
2.11 - How can I do a progress bar while I perform an action?
Often some time consuming task needs to be done in a loop, but you need a visual cue so the user isn't thinking their computer is hung. The GUI_UpdateNow() function allows you to redraw the display, even while in a function. Sample code could look like this:
int loopcount = 0;
while (1)
{
if ( ! (loopcount++ % UPDATE_INTERVAL) )
{
progressbar->SetPosition( loopcount / UPDATE_INTERVAL );
GUI_UpdateNow();
}
< do work here, and break when done >
}
2.12 - How can I call a dialog?
There are two ways - the safest and easiest to understand is called modal in other operating systems:
GUI_EventLoop(new MyWindow());This creates and makes 'MyWindow' active; when the window is closed, the function returns. Note that the window doesn't exist after the return, as the memory is deleted. Another way is to use Show for an already existing window:
CMyWindow *MyWindow=new CMyWindow();
MyWindow->Show();
... later on ...
delete MyWindow;
The Show returns immediately, so this could lead to odd
effects, like redrawing on the window underneath.
2.13 - Which is best, GUI_EventLoop() or Show()?
Using GUI_EventLoop() is preferred - the function doesn't return until the window is closed, so side effects are minimized.
2.14 - How do I use a bitmap as a background in my program?
The Draw() method in your window allows you to put default code in place so it will draw every time the program refreshes (eg. closing another window, coming in from another program, etc.). The first step is to get your bitmap into IMAGE format, with the appropriate IMAGE structure to describe it. Then you need code to add it to the Draw() function:
CMyWindow::Draw(void)
{
CWindow::Draw(); // do basic window drawing (border, etc)
RECT rect;
GetUsableRect(&rect); // actual window interior
const IMAGE *ptr=&myImageBitmap; // your bitmap
DrawImage(0,0,ptr,0,0,0,0,ptr->img_width,ptr->img_height,IMG_CMB_AND);
DrawChildren(); // draw over back with children, buttons, etc
}
2.15 - Is this the only way?
No - the previous is more general purpose (draw any image, not just a background). A more efficient way is to overload the UserBackground() function, which a window calls automatically.
void CMyWindow::UserBackground()
{
imgRectCombine(imgGetBase(),
0, 16,
myImageBitmap,
0, 0,
GetWidth(), GetHeight(),
IMG_CMB_SRC);
}
2.16 - How to I prompt the user when closing the program?
The official method is to overload your window's Close() function:
void MyWindow::Close(void)
{
bool doIClose =false; // replace with test or user prompt to close
if (doIClose)
{
CWindow::Close();
GUI_Exit();
}
else // decide against it
{
((CButton *) GetChild(0)->GetChild(0))->SetDownStatus( FALSE );
GUI_ClearStack();
Draw();
}
}
2.17 - OK, what's a magic number?
That's programming jargon for a special number. It's taken from coding from where a programmer would code a number like 640, and eventually lose track of what it means. In time, it cannot be changed without affecting the program, but it's hard to remember why it exists or what it's for - in other words, it attains 'magical' qualities. It can also apply to a number with unique properties, such as identification numbers that must match for an object to be valid.
2.18 - The first entry in the Default FONTGROUP doesn't make any sense - why?
It is identification data (specifically a Magic Number and ID), and is not part of any font.
2.19 - Some FONTGROUP entries are zero - why?
The font entry is an offset, and when it is zero, it indicates the font doesn't exist. However, the entry can exist, even if the font doesn't. Let it be a reminder to check your FONTGROUP data carefully before use.
2.20 - Who is responsible for handling fonts - the operating system or the programmer?
Right now the fonts are built into the program, so the programmer has the control. The official word is that the OS (ie Franklin) may assert more control in the future. Until then, avoid functions that change the general settings (like GUI_SetDefaultFont) and only change your own program's font settings (via SetFont).
2.21 - Are there any plans for Franklin to provide additional fonts or font groups?
No.
2.22 - Where can I get more information on creating fonts?
An article is planned in the future; until then, Franklin's CDK (Content Development Kit) can be helpful.
Previous Section
Next Section