GPS-Linked Astronomical Clock "pclock" -3 / 3-
Creating Original Controls
Creating original controls is simple with SophiaFramework UNIVERSE standard control classes like "Button" or "Combo Box".
pclock's List Box, Calendar and Text Box (which only allows numbers to be inputted) are examples of original controls created using SophiaFramework UNIVERSE's standard control classes.
The following example using the "SGRNumberTextControl" Class will demonstrate how to build original controls.
1. How to Get an Event
All original control classes inherit from the "SFRControl" class.
When a Control Box/Button is selected, it is said to be "Focused", and a light green frame around it indicates this status. The control's parent responder is notified of the change in the "Focused/Unfocused" status flag.
When the "Select Key" is pushed while a control's status is "Focused", that control will be "Targeted" and can receive events.
Here are the steps for a control to get an event:
- Get "Focused"
- Get "Targeted"
With native BREW these steps require the button to be pressed twice. But using SopfiaFramework's macro, the two steps are processed with a single button press.
Control Execution Macros
- SFMRESPONDERTYPE
- SFMRESPONDERATTRIBUTE
- SFRRESOPONDERBEHAVIOR
Please refer to the SGRNumberTextControl code below to understand how these macros work.
// SGRNumberTextControl.hpp
SFMRESPONDERTYPE(NUMBERTEXTCONTROL, TYPE_CONTROL)
SFMRESPONDERATTRIBUTE(NUMBERTEXTCONTROL,
four_char_code('N', 'u', 'm', 't'))
SFMRESPONDERBEHAVIOR(NUMBERTEXTCONTROL, BEHAVIOR_CONTROL,
STATUS_VISIBLE | PROPERTY_DIRECT,
APPEARANCE_SHADOW | PROPERTY_TRAVEL | PROPERTY_SCROLLABLE)
The "SFMRESPONDERTYPE" macro declares the type of "NUMBERTEXTCONTROL" and allows it to define the control. The "SFMRESPONDERATTRIBUTE" macro associates "NUMBERTEXTCONTROL" with the string attribute "Numt".
The string "Numt" is used when the "GetFont()" function searches for the control. Any string is acceptable as long as it does not consist of all lower case letters; some lower case strings are reserved in SophiaFramework UNIVERSE.
The "SFMRESPONDERBEHAVIOR" macro sets the constants of "NUBERTEXTCONTROL". The third argument is for constants that are true, the fourth is for those that are false.
"SGRNumberTextControl" would like to be "Targeted" when "Focused", so "PROPERTY_DIRECT" is part of the third argument. Scrolling is not required, so "PROPERTY_SCROLLABLE" is part of the fourth argument.
The following table presents the constants and their meanings.
| Constant | Meaning |
|---|---|
| STATUS_VISIBLE | Visible / Invisible |
| STATUS_ENABLE | Manipulation enabled / disabled |
| STATUS_FOCUS | Focused / Unfocused |
| STATUS_TARGET | Targeted / Not targeted |
| APPEARANCE_FLOATING | Floating window (reserved) |
| APPEARANCE_TRANSPARENT | Transparent |
| APPEARANCE_SHADOW | Shadow (reserved) |
| PROPERTY_DIRECT | Always targeted |
| PROPERTY_SELECT | When targeted, bring it to the front |
| PROPERTY_TRAVEL | When its child's responder is focused, auto-scroll so that the responder is visible |
| PROPERTY_CLOSABLE | Clear key can be used to delete |
| PROPERTY_MOVABLE | Movable |
| PROPERTY_SCROLLABLE | Scrollable |
3. Initializing the control
The macro (NUMBERTEXTCONTROL) which defines the behavior of the control is used in the constructor as follows.
// SGRNumbertextControl.cpp
SGRNumberTextControl::SGRNumberTextControl(/* omit */)
: SFRControl(responder, rect, SFXMargin(3, 3, 3, 3),
SFMRESPONDERFILTER(NUMBERTEXTCONTROL, BEHAVIOR_NUMBERTEXTCONTROL),
ATTRIBUTE_NUMBERTEXTCONTROL), /* omit */
{
if (_digit < 1) {
_digit = 1;
}
...
The defined behavior of the control must be passed to the constructor's fourth argument.
The "BEHAVIOR" and "ATTRIBUTE" arguments before "NUMBERTEXTCONTROL" are generated by the "SFMRESPONDERATTRIBUTE" and "SFRRESPONDERBEHAVIOR" macros.
"SGRNumberTextControl" can now be used like any other regular control in SophiaFramework UNIVERSE.
Define the event handler, and the implementation is complete.