@...GETBOX
DEFINE GETBOX 
Creates a GetBox control.
  

Windows implementation of Harbour`s GET Class

SYNTAX

Standard Window:

@ <nRow> ,<nCol> GETBOX <ControlName>
[ ID <nId> ]
[ OF | PARENT | DIALOG <ParentWindowName> ]
[ HEIGHT <nHeight> ]
[ WIDTH <nWidth> ]
[ FIELD <FieldName> ]
[ VALUE <nValue> ]
[ ACTION | ONCLICK | ON CLICK <OnActionProcedure> | <bBlock> ]
[ ACTION2 <OnAction2Procedure> | <bBlock> ]
[ IMAGE <cBitmapName> | <acBitmapName> ]
[ BUTTONWIDTH <nButtonWidth> ]
[ PICTURE <cPicture> ] //** format function and template string
[ VALID <valid> | RANGE <min>,<max> ] // VALID - postvalidation function or codeblock which must return logical value
// RANGE - allowed range of values
[ VALIDMESSAGE <cValidMessage> ]
[ MESSAGE <cMessage> ] // text to display on STATUSBAR Item(1) when getbox have focus

[ WHEN <when> ] // prevalidation function or codeblock (if return .f. GetBox is readonly
[ READONLY ]
[ FONT <cFontName> SIZE <nFontSize> ]
[ BOLD ] [ ITALIC ] [ UNDERLINE ] [ STRIKEOUT ]
[ PASSWORD ]
[ TOOLTIP <cToolTipText> | <acToolTipText> ]
[ BACKCOLOR <anBackColor> ] // * or <anBackColor, anReadOnlyBackColor, anAciveBackColor>
[ FONTCOLOR <anFontColor> ] // * or <anFontColor, anReadOnlyFontColor, anActiveFontColor>
[ ON CHANGE <OnChangeProcedure> | <bBlock> ]
[ ON GOTFOCUS <OnGotFocusProcedure> | <bBlock> ]
[ ON LOSTFOCUS <OnLostFocusProcedure> | <bBlock> ]
[ ON INIT <bInit> ]
[ RIGHTALIGN ]
[ INVISIBLE ]
[ NOTABSTOP ]
[ NOBORDER ]
[ NOMINUS ]
[ HELPID <nHelpId> ]

Alternate Syntax:

DEFINE GETBOX <ControlName>

[ ID <nId> ]
[ PARENT <ParentWindowName> ]
COL <nCol>
ROW <nRow>
[ HEIGHT <nHeight> ]
[ WIDTH <nWidth> ]
[ FIELD <FieldName> ]
[ VALUE <nValue> ]
[ ACTION  <OnActionProcedure> | <bBlock> ]
[ ACTION2 <OnAction2Procedure> | <bBlock> ]
[ IMAGE <cBitmapName> | <acBitmapName> ]
[ BUTTONWIDTH <nButtonWidth> ]
[ PICTURE <cPicture> ]
[ VALID <valid> ]
[ VALIDMESSAGE <cValidMessage> ]
[ MESSAGE <cMessage> ]
[ WHEN <when> ]
[ READONLY < .T. | .F.> ]
[ FONTNAME <cFontName> ]
[ FONTSIZE <nFontSize> ]
[ FONTBOLD < .T. | .F.> ]
[ FONTITALIC < .T. | .F.> ]
[ FONTUNDERLINE < .T. | .F.> ]
[ FONTSTRIKEOUT < .T. | .F.> ]
[ PASSWORD < .T. | .F.> ]
[ TOOLTIP <cToolTipText> | <acToolTipText> ]
[ BACKCOLOR <anBackColor> ]
[ FONTCOLOR <anFontColor> ]
[ ONCHANGE <OnChangeProcedure> | <bBlock> ]
[ ONGOTFOCUS <OnGotFocusProcedure> | <bBlock> ]
[ ONLOSTFOCUS <OnLostFocusProcedure> | <bBlock> ]
[ ON INIT <bInit> ]
[ RIGHTALIGN < .T. | .F.> ]
[ INVISIBLE < .T. | .F.> ]
[ NOTABSTOP < .T. | .F.> ]
[ NOBORDER ]
[ NOMINUS < .T. | .F.> ]
[ HELPID <nHelpId> ]
[ ONINIT <bInit> ]

END GETBOX

Optional focused colors tuning::

SET GETBOX FOCUS BACKCOLOR [ TO <anBackColor> ]

SET GETBOX FOCUS FONTCOLOR TO <anFontColor>


DESCRIPTION:
nRow, nCol
Position in the area of ??the window in pixels.
nWidth, nHeight
The desired size of the GetBox Control in pixels.
nId
The ID identifier this Control in Dialog Window
ControlName
A reference to the GetBox Control
ParentWindowName
A reference to the Parent Window.
nHelpID
The help topic identifier for this Control
Field
Specifies the Field Name for the GetBox control
nValue
Specifies a startup value for the GetBox control
OnActionProcedure
An action to be performed when Clicking the GetBox control
OnAction2Procedure
?
cBitmapName | acBitmapName
?
nButtonWidth
?
cPicture
Sets the display and editing rules of the GetBox
Valid
Specifies the postValidation action to be performed
Min, Max
Specifies the Range Min and Max
cValidMessage
 
cMessage
Specifies the Text to display on StatusBar Item(1) when GetBox have focus
When
Specifies the preValidation action to be performed
cFontName
Specifies the Font Name
cFontSize
Specifies the Font Size
cToolTipText> | acToolTipText
Specifies the Text for the ToolTip
anBackColor
Specifies the Background Color
anReadOnlyBackColor
Specifies the Background Color when set in READONLY
anAciveBackColor
?
OnGotFocusProcedure
An action to be performed when control Got Focused
OnChangeProcedure
An action to be performed when control value changes
OnLostFocusProcedure
An action to be performed when control Lost Focused
 
 
READONLY
Specifies that this control is in READOBLY mode
PASSWORD
Specifies that we are inputing a password and to show *
RIGHTALIGN
?
INVISIBLE
The visibility property specifies whether or not a control is visible
NOTABSTOP
Stop the control to receive focus and participate in the tabbing sequence
NOBORDER
Specifies not to draw any border around the GetBox control
NONINUS
?


** GETBOX supported PICTURE Format Functions

Function
Type
Action
A
C
Allows only alphabetic characters
B
N
Displays numbers left-justified.
C
N
Displays CR after positive numbers.
D
D,N
Displays dates in SET DATE format.
K
All
Deletes default text if first key is not a cursor key.
X
N
Displays DB after negative numbers.
Z
N
Displays zero as blanks.
(
N
Displays negative numbers in parentheses with leading spaces.
)
N
Displays negative numbers in parentheses without leading spaces.
!
C
Converts alphabetic character to uppercase.
 
 

!>> unsupported Format Functions from Harbour Get class :
R
C
Nontemplate characters are inserted in the display
but not saved in the variable.
S<n>
C
Allows horizontal scrolling within a GET. <n> is
E
D,N
Displays dates with day and month inverted
independent of the current DATE SETting, numerics
with comma and period reverse (European style).
an integer that specifies the width of the region.

** GETBOX supported PICTURE Template Symbols

Template
Action
A
Allows only alphabetic characters
N
Allows only alphabetic and numeric characters
X
Allows any character
9
Allows digits for any data type including sign for numerics
#
Allows digits, signs and spaces for C,N type
L
Allows only T, F, Y or N
Y
Allows only Y or N
!
Converts an alphabetic character to uppercase
$
Displays a dollar sign in place of a leading space in a numeric
*
Displays an asterisk in place of a leading space in a numeric
.
Displays a decimal point
,
Displays a comma

FontColor and BackColor property can be defined as RGB array or array of RGBArrays
for Enable ,ReadOnly and Focused (active) stage.
ReadOnly stage preserve defined FontColor and BackColor
VALID and RANGE clauses are checked when control lost focus
User can not leave control if defined validation function (or codeblock) return false
or entered value is out of defined range.
WHEN clause is checked when control become focus . If defined here function or codeblock
used as WHEN param return false, control status is changed to readonly (noneditable).

Navigation Keys inside GETBOX:
RETURN (ENTER),
TAB, ARROW_DOWN
move focus to the next active control
ARROW_UP
move focus to the previous active control
ESC
return original (initial) control value if initial value was changed or move focus to the next active control if initial value remains unchanged
ARROW_LEFT,
ARROW_RIGHT
move caret left/right
HOME,END
move caret to first and last editable position inside control
INS
change insertmode ON/OFF (as far change caret shape)
CTRL+"A"
select all editable contents
CTRL+ARROW_UP,
CTRL+ARROW_DOWN
increment/decrement N,D type contents (+/-1 or +/-1 day)
or change value of logical content to opposite value (Y/N)
CTRL+"Y"
clear the current value

Getbox support also all typical clipboard operations ( CUT (Ctrl+X), COPY (Ctrl+C) and PASTE (Ctrl+V) )


PROPERTIES:

·   Value
Set / Gets GetBox value.
Note: Getbox always return unformatted value which archive initial valuetype.  Programmer must take a care to not set new control value with different valuetype otherwise error will be generated
·   Enabled
Set / Gets enabled state of a GetBox control
·   Visible          
Set / Gets visible a GetBox control.
·   Row
Set / Gets row position of a GetBox control.
·   Col   
Set / Gets column position of a GetBox control.
·   Width
Set / Gets width of a GetBox control.
·   Height
Set / Gets height of a GetBox control.
·   Action
Set / Gets action of a GetBox control.
·   FontName
Set / Gets GetBox control's font name.
·   FontSize
Set / Gets GetBox control's font size.
·   FontBold
Set / Gets GetBox control's font bold property
·   FontItalic
Set / Gets GetBox control's font italic property
Set / Gets GetBox control's font underline property
Set / Gets GetBox control's font strikeout property
·   FontColor
Set / Gets the foreground color for text within the GetBox
·   BackColor
Set / Gets the background color for text within the GetBox
·   ToolTip
Set / Gets GetBox control's Tooltip text.
·   Picture
Set / Gets the image name of a GetBox control.
·   Cargo
Set / Gets user property 'Cargo' for GetBox control
Set / Gets the character with messages to show when valid procedure returns .F.
·   Name (R)
Retrieves the name of a GetBox control.
·   DisplayValue (R)
Gets value - formatted characters string from GetBox
·   Parent (D)
Set the name as character identifier of the control.
·   Parent(D)
Set the name as character identifier of the parent window.
·   HelpId (D)
Set the numeric help topic identifier of the control.
·   Field(D)
Set the Field data of active database.
·   ReadOnly
Set / Gets GetBox control's readonly property
·   RightAlign(D)
Right-aligns text in a GetBox control.
·   NoTabStop(D)
Sets whether an element behavior can't receive focus and participate in the tabbing sequence

D: Available at control definition only
R: Read-Only

EVENTS:

·   OnGotFocus
Action to be performed when getting the focus
·   OnChange
Action to be performed when generic changing of the control
Action to be performed when losing the focus.
·   OnClick
Action to be performed when generic clicking of the button of control
·   Action2
Action to be performed when generic clicking of the 2th button of control

METHODS:

·   Show
Shows a GetBox control
·   Hide
Hides a GetBox control
·   Redraw
Redraw a Control
·   SetFocus
Gives the focus to a GetBox control
·   Release
Releases a GetBox control from memory
·   Refresh
Reread data from database`s field defined in FIELD clause.
(!)This method can be used only if FIELD clause is set.
·   Save
Save data for Control GetBox
·   SaveAs
Save a GetBox control as BitMap file.

EXAMPLE:

See demo in :
\Samples\Basic\GetBox
      \Samples\Basic\GetBoxValid