@...BROWSE
DEFINE BROWSE
Creates a browse control
   
A Browse control is a general purpose database browser.

SYNTAX

Standard Window:

[ @ <nRow> ,<nCol> ] BROWSE <ControlName>
[ ID <nId> ]
[ OF | PARENT | DIALOG <ParentWindowName> ]
WIDTH <nWidth>
HEIGHT <nHeight>
HEADERS <acHeaders>
WIDTHS <anWidths>
WORKAREA <WorkAreaName>
FIELDS <acFields>
[ VALUE <nValue> ]
[ FONT <cFontName> SIZE <nFontSize> ]
[ BOLD ] [ ITALIC ] [ UNDERLINE ] [ STRIKEOUT ]
[ TOOLTIP <cToolTipText> ]
[ BACKCOLOR <anBackColor> ]
[ DYNAMICBACKCOLOR <anDynamicBackColor> ]
[ DYNAMICFORECOLOR <anDynamicForeColor> ]
[ FONTCOLOR <anFontColor> ]
[ ON GOTFOCUS <OnGotFocusProcedure> | <bBlock> ]
[ ON CHANGE <OnChangeProcedure> | <bBlock> ]
[ ON LOSTFOCUS <OnLostFocusProcedure> | <bBlock> ]
[ [ ON DBLCLICK <OnDblClickProcedure> | <bBlock> ] | [ EDIT [ INPLACE ] ] [ APPEND  ]
[ INPUTITEMS <inputitems> ]
[ DISPLAYITEMS <DisplayItems> ]
[ ON HEADCLICK <aOnHeadClickProcedure> | <abBlock> ]
[ WHEN <abWhen> ]
[ VALID <abBlock> ]
[ VALIDMESSAGES <acValidationMessages> ]
[ PAINTDOUBLEBUFFER lDoubleBuffer ]
[ READONLY <alReadOnlyFields> ]
[ LOCK ]
[ DELETE ]
[ NOLINES ]
[ IMAGE <acImageNames> ]
[ JUSTIFY <anJustifyValue> ]
[ NOVSCROLL ]
[ HELPID <nHelpId> ]
[ BREAK ]
[ COLUMNSORT <ColumnSort> ]
[ HEADERIMAGE <aImageHeader> ]
[ NOTABSTOP ]
[ ON INIT <bInit> ]

Dialog Window:

REDEFINE BROWSE <ControlName>
ID <nId>
[ OF | PARENT | DIALOG <ParentWindowName> ]
HEADERS <acHeaders>
WIDTHS <anWidths>
WORKAREA <WorkAreaName>
FIELDS <acFields>
[ VALUE <nValue> ]
[ FONT <cFontName> SIZE <nFontSize> ]
[ BOLD ] [ ITALIC ] [ UNDERLINE ] [ STRIKEOUT ]
[ TOOLTIP <cToolTipText> ]
[ BACKCOLOR <anBackColor> ]
[ DYNAMICBACKCOLOR <anDynamicBackColor> ]
[ DYNAMICFORECOLOR <anDynamicForeColor> ]
[ FONTCOLOR <anFontColor> ]
[ ON GOTFOCUS <OnGotFocusProcedure> | <bBlock> ]
[ ON CHANGE <OnChangeProcedure> | <bBlock> ]
[ ON LOSTFOCUS <OnLostFocusProcedure> | <bBlock> ]
[ [ ON DBLCLICK <OnDblClickProcedure> | <bBlock> ] | [ EDIT  [ INPLACE ] ] [ APPEND ]
[ INPUTITEMS <inputitems> ]
[ DISPLAYITEMS <displayitems> ]
[ ON HEADCLICK <aOnHeadClickProcedure> | <abBlock> ]
[ WHEN <abWhen> ]
[ VALID <abBlock> ]
[ VALIDMESSAGES <acValidationMessages> ]
[ PAINTDOUBLEBUFFER lDoubleBuffer ]
[ READONLY <alReadOnlyFields> ]
[ LOCK ]
[ DELETE ]
[ NOLINES ]
[ IMAGE <acImageNames> ]
[ JUSTIFY <anJustifyValue> ]
[ NOVSCROLL ]
[ HELPID <nHelpId> ]
[ BREAK ]
[ COLUMNSORT <ColumnSort> ]
[ HEADERIMAGE <aImageHeader> ]
[ NOTABSTOP ]
[ ON INIT <bInit> ]

Splitbox Version

BROWSE <ControlName>
[ OF <ParentWindowName> ]
[ WIDTH <nWidth> ]
[ HEIGHT <nHeight> ]
[ HEADERS <acHeaders> ]
[ WIDTHS <anWidths> ]
[ WORKAREA <WorkAreaName> ]
[ FIELDS <acFields> ]
[ VALUE <nValue> ]
[ FONT <cFontName> SIZE <nFontSize> ]
[ BOLD ] [ ITALIC ] [ UNDERLINE ] [ STRIKEOUT ]
[ TOOLTIP <cToolTipText> ]
[ BACKCOLOR <anBackColor> ]
[ DYNAMICBACKCOLOR <anDynamicBackColor> ]
[ DYNAMICFORECOLOR <anDynamicForeColor> ]
[ FONTCOLOR <anFontColor> ]
[ ON GOTFOCUS <OnGotFocusProcedure> | <bBlock> ]
[ ON CHANGE <OnChangeProcedure> | <bBlock> ]
[ ON LOSTFOCUS <OnLostFocusProcedure> | <bBlock> ]
[ [ ON DBLCLICK <OnDblClickProcedure> | <bBlock> ] | [ EDIT [ INPLACE ] ] [ APPEND  ]
[ INPUTITEMS <inputitems> ]
[ DISPLAYITEMS <DisplayItems> ]
[ ON HEADCLICK <aOnHeadClickProcedure> | <abBlock> ]
[ WHEN <abWhen> ]
[ VALID <abValid> ]
[ VALIDMESSAGES <acValidationMessages> ]
[ PAINTDOUBLEBUFFER lDoubleBuffer ]
[ READONLY <alReadOnlyFields> ]
[ LOCK ]
[ DELETE ]
[ NOLINES ]
[ IMAGE <acImageNames> ]
[ JUSTIFY <anJustifyValue> ]
[ NOVSCROLL ]
[ HELPID <nHelpId> ]
[ BREAK ]
[ COLUMNSORT <ColumnSort> ]
[ HEADERIMAGE <aImageHeader> ]
[ NOTABSTOP ]
[ ON INIT <bInit> ]

Alternate Syntax:

DEFINE BROWSE <ControlName>
[ ID <nId> ]
[ PARENT <ParentWindowName> ]
COL <nCol>
ROW <nRow>
WIDTH <nWidth>
HEIGHT <nHeight>
HEADERS <acHeaders>
WIDTHS <anWidths>
FIELDS <acFields>
[ VALUE <nValue> ]
WORKAREA <WorkAreaName>
[ FONTNAME <cFontName> ]
[ FONTSIZE <nFontSize> ]
[ FONTBOLD < .T. | .F.> ]
[ FONTITALIC < .T. | .F.> ]
[ FONTUNDERLINE < .T. | .F.> ]
[ FONTSTRIKEOUT < .T. | .F.> ]
[ TOOLTIP <cToolTipText> ]
[ BACKCOLOR <anBackColor> ]
[ DYNAMICBACKCOLOR <abDynamicBackColor> ]
[ DYNAMICFORECOLOR <abDynamicForeColor> ]
[ FONTCOLOR <anFontColor> ]
[ ONGOTFOCUS <OnGotFocusProcedure> | <bBlock> ]
[ ONCHANGE <OnChangeProcedure> | <bBlock> ]
[ ONLOSTFOCUS <OnLostFocusProcedure> | <bBlock> ]
[ ONDBLCLICK <OnDblClickProcedure> | <bBlock> ]
[ ALLOWEDIT < .T. | .F.> ]
[ INPLACEEDIT < .T. | .F.> ]
[ ALLOWAPPEND < .T. | .F.> ]
[ INPUTITEMS <inputitems> ]
[ DISPLAYITEMS <DisplayItems> ]
[ ONHEADCLICK <aOnHeadClickProcedure> | <abBlock> ]
[ WHEN <abWhen> ]
[ VALID <abValid> ]
[ VALIDMESSAGES <acValidationMessages> ]
[ PAINTDOUBLEBUFFER < .T. | .F.> ]
[ READONLYFIELDS <alReadOnlyFields> ]
[ LOCK < .T. | .F.>  ]
[ ALLOWDELETE < .T. | .F.> ]
[ NOLINES < .T. | .F.> ]
[ IMAGE <acImageNames> ]
[ JUSTIFY <anJustifyValue> ]
[ VSCROLLBAR < .T. | .F.> ]
[ HELPID <nHelpId> ]
[ BREAK < .T. | .F.> ]
[ COLUMNSORT <ColumnSort> ]
[ HEADERIMAGE <aImageHeader> ]
[ NOTABSTOP < .T. | .F.> ]
[ ON INIT <bInit> ]

END BROWSE

DESCRIPTION: 

nRow, nCol
Position in the area of ??the window in pixels.
nWidth, nHeight
The desired size of the Browse Control in pixels.
nId
The ID identifier this Control in Dialog Window
ControlName
A reference to the Browse Control
ParentWindowName
A reference to the Parent Window.
acHeaders
A list of text expressions for headers of each column
anWidths
A list of sizes for each column in pixels
WorkAreaName
A reference to the WorkArea.
acFields
A list of text expressions to display as columns data
nValue
A RecNo() as the start position in the Browse control
cFontName
Specifies the Font Name
nFontSize
Specifies the Font Size
OnChangeProcedure
An action to be performed when selecting a new row.
OnGotFocusProcedure
An action to be performed when Browse is focused.
OnLostFocusProcedure
An action to be performed when Browse is lost focused.
OnDblClickProcedure
An action to be performed when Double Left clicking.
abBlock
An expression to be validated when the Browse loses its focus.
alReadOnlyFields
A list of logical expressions for the fields…
acImageNames
A list of image name for each column
aOnHeadClickProcedure
A list of actions to be executed when a certain column header is clicked with the mouse.
abWhen
A Function or CodeBlock to evaluate indicating if the Browse is or not enable..
abValid
A list of Validation Codeblock for each column
acValidationMessages
A list of associated messages of fields displayed when editable Field loses its focus and is not valid.
anJustifyValue
A list of Justification value for each column (see Justify table below)
abDynamicBackColor
A list of codeblock returning a Background RGB array for each column
abDynamicForeColor
A list of codeblock returning a Foreground RGB array for each column
cToolTipText
Browse control's ToolTip text.
anBackColor
A list of Background color for text
anFontColor
A list of Foreground color for text
InputItems
A list of array (see Remarks below for further detail)
DisplayItems
A list of array (see Remarks below for further detail)
nHelpId
The help topic identifier for this Control
aImageHeader
A list of Image for the header of each column
lDoubleBuffer
?
 
 
LOCK
Perform a RLock() for DELETE operation only
DELETE
Delete browse row
NOLINES
Do not draw grid line within the browse control
NOVSCROLL
Specifies that we want to Vertical scrolling
BREAK
?
NOTABSTOP
Stop the control to receive focus and participate in the tabbing sequence


 JUSTIFY TABLE: (see \include\i_browse.ch)

DEFINE Value
Value
 
 
BROWSE_JTFY_LEFT
0
BROWSE_JTFY_RIGHT
1
BROWSE_JTFY_CENTER
2
BROWSE_JTFY_JUSTIFYMASK
3


REMARKS:

·     Value property selects a record by its number ( RecNo() ) 

·     Value property returns selected record number ( RecNo() )

·     Browse control does not change the active work area

·     Browse control does not change the record pointer in any area (nor change selection when it changes) when SET BROWSESYNC is OFF (the default)

·     You can programmatically refresh it using refresh method.

·     Variables called <MemVar>.<WorkAreaName>.<FieldName> are created for validation in browse editing window. You can use it in VALID array.

·     Using APPEND clause you can add records to table associated with WORKAREA clause. The hotkey to add records is Alt+A or Ctrl+Alt+A or Shift+Alt+A.. Append Clause Can't Be Used With Fields Not Belonging To Browse WorkArea

·     Using DELETE clause allows to mark selected record for deletion pressing <Del> key

·     The leftmost column in a browse control must be left aligned.

·     When used in control definition, Header property must be loaded with a character array containing as elements as control columns.

·     SET BROWSESYNC: When is set to ON, BROWSE control will move the record pointer in its workarea according to user selection or value property programmatic setting.

·     Setting 'Value' to reccount()+1 (EOF) will cause that browse windows get empty (no records will be showed).

·     Browse controls supports now the code-blocks with an input Value as parameter in the VALIDMESSAGES array

·     The following parameters MUST be in the same column order in order to work properly: acHeaders, anWidths, acFields, alReadOnlyFields, abValidBlock, acValidationMessages, anJustifyValue, abWhen, abValid, abDynamicBackColor, abDynamicForeColor,, aImageHeader,  aOnHeadClickProcedure

·     'InputItems' property allows to control data input in browse control. This property is an array (one element for each browse column)  each element (if specified) must be a two dimensional array. The first column in the array must contain the data to be shown to the user. the second column must contain the data to be stored in the table (ID) for each text row in the array. For a demo see \samples\Basic\Browse_5

·     'DisplayItems' property allows to control data display in browse control. This property is an array (one element for each browse column) each element (if specified) must be a two dimensional array. the first column in the array must contain the text to be shown to the  user. The second column      must contain the ID for each array row.   The array will be searched for a corresponding ID in the table to show the right text in each cell. If no correspondence is found, the cell  will be blank. For a demo see \samples\Basic\Browse_5


PROPERTIES:

 

·   Value
Set / Gets browse value - selected record number
·   Enabled
Set / Gets enabled state of a browse control
·   Visible          
Set / Gets visible a browse control.
·   Row
Set / Gets row position of a browse control.
·   Col   
Set / Gets column position of a browse control.
·   Width
Set / Gets width of a browse control.
·   Height
Set / Gets height of a browse control.
·   Header (nColumnIndex)
Set / Gets header text in a browse control.
·   HeaderImage (nColumnNumber)
Set / Gets header image in a browse control.
Set / Gets column display position in a browse control
·   FontName
Set / Gets browse control's font name.
·   FontSize
Set / Gets browse control's font size.
·   FontBold
Set / Gets browse control's font bold property
·   FontItalic
Set / Gets browse control's font italic property
Set / Gets browse control's font underline property
Set / Gets browse control's font strikeout property
·   ToolTip
Set / Gets browse control's tooltip text.
·   BackColor
Set / Gets the background color for text within the control
·   FontColor
Set / Gets the foreground color for text within the control
·   Cargo
Set / Gets user property 'Cargo' for browse control
·   Name (R)
Retrieves the name of a browse control.
·   ColumnCount(R)
Get item count in a Browse control.
·   Parent(D)
Set the name as character identifier of the parent window.
·   HelpId (D)
Set the numeric help topic identifier of the control.
·   Break(D)
Control passes to the statement that follows the terminated statement.
·   Widths(D)
Specifies column widths for Browse and Grid controls. It must be specified as a numeric array containing one element for each column in the control
·   Fields(D)
A character array (one element per column) specifying fields for a Browse control
·   WorkArea(D)
Database workarea name
·   Valid(D)
Codeblock array (one element per column) that is evaluated after field editing for Browse control
·   ValidMessages(D)
Character array (one element per column) with messages to show when valid procedure returns .F.
·   ReadOnlyFields(D)
Specifies read-only columns on a Browse control as a logical array
·   Lock(D)
Specifies whether Browse control should lock records when saving changes made interactively by the user
Sets whether records can be added to a Browse control.
Sets whether records can be deleted in a Browse control.
·   AllowEdit
Sets whether records can be edited in a Browse control.
·   InPlaceEdit(D)
 
·   NoLines(D)
Specifies whether lines are shown in a Grid or Browse control
·   Image(D)
Specifies a character array containing image filenames or resource names to be used with Browse controls
·   Justify(D)
Numeric array (one element for each column) containing justification constants for Browse controls
·   VScrollBar(D)
Specifies whether a vertical scrollbar will be included in the Browse control
·   When(D)
Codeblock array (one element per column) that is evaluated prior to field editing for Browse control
Dynamically Set The Background Color For a Browse Cell
Dynamically Set The Foreground Color For a Browse Cell
·   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.
·   OnDblClick
Action to be performed when Double Left clicking.
List of actions to be executed when a certain column header is clicked with the mouse

METHODS:

·   Show
Shows a GUI object
·   Hide
Hides a GUI object
·   Redraw
Redraw a Control
·   SetFocus
Gives the focus to a control.
·   Refresh
Repaint a Control
·   Release
Releases a control from memory
·   ColumnAutoFit (nColumn)
Set widths of a column to fit column contents text & column contents.
·   ColumnAutoFitH (nColumn)
Set widths of a column to fit column header text & column contents
Set widths of all columns to fit each column contents  text & column contents.
Set widths of all columns to fit each column header text & column contents.
Update enables for Browse control
Update disables for Browse control
·   SaveAs
Save Control as BitMap file.

EXAMPLE:

See demos in :
\Samples\Basic\Browse_1
\Samples\Basic\Browse_3
\Samples\Basic\Browse_4
\Samples\Basic\Browse_5
\Samples\Basic\Browse_6
\Samples\Basic\Browse_7
\Samples\Basic\Browse_8
\Samples\Basic\ImageBrowse1
\Samples\Basic\ImageBrowse2
\Samples\Basic\DualBrowse
\Samples\Basic\Browse_Sort


and sample in Chapter:
 Data-Controls I: BROWSE