Creates an Application Part to edit databases
APPEDIT ;
[INTO <oAppEdit>] ;
[ FIELDS <cFieldName,...> ] ;
[ PARENT <oParent> ] ;
[ POSITION <pos1> [, <pos2>] ] ;
[ SIZE <size1> [, <size2>] [PERCENT] ] ;
[ TITLE <cTitle> ] ;
[ COLOR <nForeGround> [, <nBackGround>] ] ;
[ FONT <cFontCompoundName> ] ;
[ HEADING <headingOptions> ] ;
[ CAPTION <captionOptions> ] ;
[ NOACTION <nSuppress> ] ;
[ STYLE PLAIN | 3D | FANCY | <nStyle> ] ;
[ BITMAP <nBitmapID> [ FIT ] ]
[ ALIAS <cAlias> ] ;
[ FOR <lForCondition> ] ;
[ WHILE <lWhileCondition> ] ;
[ SEEK <exprSeek> ] ;
[ TRIGGER <deleteFunc> [ON] DELETE ] ;
[ TRIGGER <insertFunc> [ON] INSERT ] ;
[ TRIGGER <updateFunc> [ON] UPDATE ] ;| <pos1> | Value | <pos2> | Value | Description |
|---|---|---|---|---|
| Array | {nX,nY} | n.a. | NIL | <pos1> is an array containing grafic coordinates for the AppEdit window |
| Numeric | nRow | Numeric | nCol | <pos1> is a numeric value used as row coordinate, and <pos2> specifies the column coordinate according to a text mode window |
| Key word | TOP | Key word | TOP | The AppEdit window is displayed |
| Key word | LEFT | Key word | LEFT | at the top, left, bottom, right |
| Key word | BOTTOM | Key word | BOTTOM | and/or centered within its parent, |
| Key word | RIGHT | Key word | RIGHT | according to the keywords used |
| Key word | CENTER | Key word | CENTER | for positioning |
| <size1> | Value | <size2> | Value | Description |
|---|---|---|---|---|
| Array | {nXsize,nYsize} | n.a. | NIL | A two element array defines the size in pixel |
| Numeric | nHeight | Numeric | nWidth | Two numeric values specify the number of rows and columns according to a text mode window |
HEADING <cHeadingText> ;
[ COLOR <nForeGround> [, <nShadow>] ] ;
[ ALIGN LEFT | CENTER | RIGHT ] ;
[ FONT <cFontCompoundName> ]
CAPTION ;
[ COLOR <nForeGround> [, <nShadow>] ] ;
[ ALIGN LEFT | CENTER | RIGHT ] ;
[ FONT <cFontCompoundName> ]
| Constant | Description |
|---|---|
| APPACTION_NOGOTOP | Pushbutton "First" is suppressed |
| APPACTION_NOPREVIOUS | Pushbutton "Previous" is suppressed |
| APPACTION_NONEXT | Pushbutton "Next" is suppressed |
| APPACTION_NOGOBOTTOM | Pushbutton "Last" is suppressed |
| APPACTION_NOINSERT | Pushbutton "New" is suppressed |
| APPACTION_NODELETE | Pushbutton "Delete" is suppressed |
| APPACTION_NOCANCEL | Pushbutton "Cancel" is suppressed |
| APPACTION_NOEDIT | Pushbutton "Edit" is suppressed |
| APPACTION_NOSEEK | Pushbutton "Seek" is suppressed |
| APPACTION_NONAVIGATION | Pushbuttons for navigation are suppressed |
| APPACTION_NOMODIFY | Pushbuttons for editing are suppressed |
| APPACTION_NONE | No pushbuttons are displayed |
| APPACTION_NOFIELDS | Fields are not automatically created |
| Constant | Description |
|---|---|
| APPSTYLE_FANCY | Is equal to STYLE FANCY |
| APPSTYLE_3D | Is equal to STYLE 3D |
| APPSTYLE_PLAIN | Is equal to STYLE PLAIN |
| APPSTYLE_NOBORDER | The border of the dialog window is suppressed |
| APPSTYLE_NOTITLEBAR | The title of the dialog window is suppressed |
| APPSTYLE_NOFRAMECONTROLS | Control elements in the title bar are suppressed (maximize, minimize button and system menu) |
| APPSTYLE_NOHEADING | The heading of the AppEdit window is suppressed |
| APPSTYLE_NOSTATUS | The status bar is suppressed |
| APPSTYLE_ACTIONICONS | Pushbuttons are displayed as icons |
| APPSTYLE_ACTIONTEXT | Pushbuttons have text captions |
| APPSTYLE_ACTIONTOP | Pushbuttons are displayed at the top of the AppEdit window |
| APPSTYLE_ACTIONLEFT | Pushbuttons are displayed on the left in the AppEdit window |
| APPSTYLE_ACTIONBOTTOM | Pushbuttons are displayed at the bottom of the AppEdit window |
| APPSTYLE_ACTIONRIGHT | Pushbuttons are displayed on the right in the AppEdit window |
| APPSTYLE_RAISED | Frames appear in raised style |
| APPSTYLE_HORIZONTAL | Fields are positioned horizontally row by row |
APPEDIT is a very powerful command that allows to program standardized edit dialogs for databases in a comfortable way. It creates an object of the AppEdit class and adds Xbase Parts, which access database fields.
Although the command has many options it is easy to use. The minimum requirements to display an edit dialog are three lines of code:
USE Customer NEW
APPEDIT
APPDISPLAY
These three lines open a database (USE), create an AppEdit object (APPEDIT), and display it (APPDISPLAY). The AppEdit window contains edit controls for all fields of the database. In addition, pushbuttons are included for database navigation. All other options of the APPEDIT command are used to configure the edit window in detail or to specify the fields and pushbuttons to be displayed.
| Key word | Description |
|---|---|
| PARENT | Defines the parent |
| POSITION | Positions the AppBrowse window within the parent |
| SIZE | Defines the size of the AppBrowse window |
| TITLE | Character string to be displayed in the title bar |
| COLOR | Defines colors for table columns |
| FONT | Defines font for table columns |
| HEADING | Defines colors, font and alignment of a heading |
| CAPTION | Defines colors, font and alignment for captions |
| STYLE | Defines display style |
| NOACTION | Suppresses default controls |
| BITMAP | Defines a background bitmap |
The most important options for display are PARENT, STYLE, POS and SIZE.
PARENT
The key word PARENT decides whether or not an AppEdit object is displayed within its own dialog window. When the option PARENT is used, the edit window is displayed without a dialog frame within the parent window. If PARENT is not specified, the AppEdit window is created having its own dialog window. It is then displayed on the desktop (AppDesktop()).
STYLE
The option STYLE defines the appearance of an AppEdit window. The default style is 3D. Three predefined styles can be selected for an AppEdit window using key words: STYLE PLAIN, STYLE 3D and STYLE FANCY.
POS
The option POS allows to position an AppEdit window within its parent window using different units for coordinates. The units 'pixel', 'text coordinates' and the key words TOP, LEFT, BOTTOM, RIGHT, CENTER are supported. This provides maximum flexibility for positioning of an AppEdit window. Different possibilities are shown below:
POS {100,200} // Array => x,y coordinates in pixel
POS 10, 20 // Numeric => Row and column coordinates
POS LEFT
POS TOP,CENTER // Key words => Default positions
A pixel-exact positioning is achieved with a two element array containing graphic x,y coordinates (the origin of the coordinate system is bottom, left). Numeric values are interpreted as row and column text-coordinates (the origin is top, left). Using key words an AppEdit window can be placed at well defined positions. The key word LEFT means, for example, that the AppEdit is displayed on the left side of its parent window. TOP, CENTER displays it at the top and centers it horizontally.
SIZE
The option SIZE defines the size of the display area of the AppEdit window (this is equal to the size of XbpDialog:drawingArea). A two element array defines the size in x and y direction (width and height), the unit is 'pixel'. Numeric values specify the number of rows and columns according to a text-mode window. If the key word PERCENT is specified, numeric values are used as percentage to calculate width and height from the size of the parent window (range 0-100).
Options for database access
The next table list all options relevant for database access:
| Key word | Description |
|---|---|
| FIELDS | Names of fields to be displayed |
| ALIAS | Alias name of the work area used for navigation |
| FOR | Condition for database records to display |
| WHILE | Condition executed after SKIP |
| SEEK | Expression executed by the "Seek" pushbutton |
| TRIGGER ON DELETE | User function executed prior to DELETE |
| TRIGGER ON INSERT | User function executed prior to APPEND BLANK |
| TRIGGER ON UPDATE | User function executed prior to REPLACE |
If database navigation is not to take place in the current work area, the alias name of the corresponding work area must be specified with the ALIAS option. The option FIELD specifies the fields to be edited in the AppEdit window. Field names must be programmed as literals or as character expressions in parentheses. If fields from multiple work areas are to be displayed, the field names must be alias referenced. Edit controls in the edit window are displayed in the same order like the fields are specified. Instead of using the FIELDS option, fields can be specified using the APPFIELD command prior to displaying the edit window with APPDISPLAY. If neither FIELDS nor APPFIELD is used the AppEdit window contains edit controls for all fields of the specified work area.
The other options for database operations are expressions, or code blocks, to be executed in case of particular database operations. Logical expressions must be used for the FOR and WHILE options. Both are evaluated after the record pointer is moved. If the FOR condition evaluates to .F. (false) the record pointer is moved until the result in .T. (true) or the end of file is reached.
Expressions for the SEEK and TRIGGER ON... options must return a numeric value that corresponds to #define constants listed in the next table:
| Constant | Description |
|---|---|
| APPOP_PROCEED | AppEdit proceeds with the database operation and refreshes the display |
| APPOP_IGNORE | AppEdit performs no database operation and does not refresh the display |
| APPOP_REFRESH | AppEdit performs no database operation and refreshes the display |
SEEK
The SEEK expression is used to call a user defined search routine from AppEdit when the "Seek" pushbutton is clicked. If return value of the expression is APPOP_PROCEED, the AppEdit window is refreshed. Otherwise the record pointer is positioned on the record that was current before the SEEK expression was evaluated.
TRIGGER
After the key word TRIGGER a character string with the name of a user defined function, or a code block, receiving one parameter must be specified. AppEdit evaluates a trigger prior to one of the database operations Insert, Update and Delete. A one dimensional array containing the current buffers of all edit controls in the AppEdit window is passed to the function, or code block, respectively. The sequence of the values in the array is defined by the sequence of field names specified with the FIELDS option (the value for the first specified field is stored in the first array element aso.) All values have the same data type like the corresponding fields (except memo fields).
The return value of the user defined function, or the trigger code block, must be one of the above listed #define constants.
TRIGGER <...> ON DELETE
The user function, or code block, is executed when the "Delete" pushbutton is clicked. By default this results in a DELETE operation. Before the current record actually gets deleted, AppEdit evaluates the DELETE trigger. If this returns APPOP_PROCEED, the AppEdit object deletes the record and refreshes the window. The return value APPOP_IGNORE suppresses deletion, and AppEdit does nothing. The window is refreshed without deleting the record, if APPOP_REFRESH is returned. In this case the user function must perform the DELETE operation.
TRIGGER <...> ON INSERT
The user function, or code block, is executed when the "Save" pushbutton is clicked while AppEdit is in INSERT mode.
AppEdit appends a blank record before writing data to the database. Prior to adding a new record AppEdit evaluates the INSERT trigger. If this returns APPOP_PROCEED, the AppEdit object appends a new record and writes data from the edit controls to the corresponding database fields. The return value APPOP_IGNORE suppresses an APPEND BLANK, and AppEdit does nothing. The window is refreshed without adding a new record, if APPOP_REFRESH is returned. In this case the user function must perform the APPEND BLANK operation and must write data to the database.
TRIGGER <...> ON UPDATE
The user function, or code block, is executed when the "Save" pushbutton is clicked while AppEdit is in EDIT mode.
By default this results in REPLACE operations. Before the data from edit controls are written to the current record, AppEdit evaluates the UPDATE trigger. If this returns APPOP_PROCEED, the AppEdit object updates the record with buffered data. The return value APPOP_IGNORE suppresses the update, and AppEdit does nothing. The window is refreshed without updating the record, if APPOP_REFRESH is returned. In this case the user function must write data to the current record. It also must guarantee record locks to be set if the database is open in SHARED mode.
// A modal AppEdit window is created in this example that edits
// all fields of a database. A DELETE trigger is used to confirm
// deletion of the current record.
#include "Appedit.ch"
#include "Gra.ch"
#include "Xbp.ch"
MEMVAR appObject
PROCEDURE AppSys
// Desktop remains application window
RETURN
PROCEDURE Main
USE Customer // Open database
APPEDIT ; // Define edit dialog
TITLE (CurDirectory() + "\" + Alias() + ".DBF") ;
HEADING "Kunden Adressen" COLOR GRA_CLR_RED ;
POSITION CENTER ;
TRIGGER "ConfirmDelete" ON DELETE
APPDISPLAY // Display AppEdit window modal
RETURN
*********************************
FUNCTION ConfirmDelete( aValues )
IF Ascan( aValues, {|x| ! Empty(x) } ) == 0
RETURN APPOP_PROCEED // All fields are empty
ENDIF // Delete record!
IF ConfirmBox( , "Do you really want to delete this record?", ;
"Delete record", ;
XBPMB_YESNO, ;
XBPMB_QUESTION ) == XBPMB_RET_NO
RETURN APPOP_IGNORE // Don't delete!
ENDIF
RETURN APPOP_PROCEED // Ok to delete
If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.