REVISIONS

eXPress++ Version Information

To simplify distribution, this Help file includes documentation on functions, commands and classes for all revisions of eXPress++.<br><br>Each command and function will include a revision letter after the short description. This letter is the revision of eXPress++ that supports the command or function.<br><br>For example, if a function has the revision 1.3 after the title, then this function is included in all versions of eXPress++ from 1.3 and above. If a function has the revision 2.0 after the title, then this function is included only in revision 2.0 and above.<br><br><br><br> 


COMPUTER

Computer System Requirements

eXpress++ requires that you have an IBM compatible 32-bit computer. dXpress is an add-on library designed only for use with Alaska Software's Xbase++, therefore the computer requirement are the same as for Xbase++.<br><br> * 486, 486-SX, or Pentium microprocessor * 20 mb of available disk space. * 32 meg total system memory * Windows 95, Windows 98 or Windows NT 4.0 * VGA/SVGA Color monitor * Microsoft-compatible mouse (optional) * Alaska Software's Xbase++ Version 1.2 or later<br><br> 


GETTING STARTED

Please read this to GET STARTED with eXPress++

If you are using ALINK.EXE as your linker, then the only eXpress++ files you need when "linking" your application are:<br><br> DCLIPX.LIB EXPRESS.RES<br><br> If you are using BLINKER.EXE (version 5.0) as your linker, then the only eXPress++ files you need when "linking" your application are:<br><br> DCLIPXB.LIB EXPRESS.RES <br><br> The files you need to distribute with your application are:<br><br> DCLIPX.DLL - Always DCLIP1.DLL - Only when using functions from this library DCLIP2.DLL - Only when using functions from this library DCHELP.DLL - Only when using DC_Help*() functions DCXML.DLL - Only when using DC_Xml*() functions. Also requires Alaska Software's ASXML10.DLL. TASKBAR.DLL - Only when using the TaskBar() function.<br><br> To see how to use eXPress++ commands in your application, check out the XDEMO.EXE program. The source code for this program is in the X*.PRG files which are located in the \EXPRESS\SAMPLE directory.<br><br> NOTE: It is recommended that you modify your AUTOEXEC.BAT file or your Windows NT Environment as follows:<br><br> SET PATH=<current PATH setting>\express\lib SET LIB=<current LIB setting>\express\lib SET INCLUDE=<current INCLUDE setting>\express\include<br><br> Before attempting to use eXPress++ commands or functions in your application, it is highly recommended that you run the XDEMO.EXE program in the \express\sample directory. The samples contain examples of how to write applications using eXPress++. If the documentation is unclear about how to accomplish a task, look at the samples.<br><br> <br><br> 


IMPORTANT

Important Notes (Please Read)

eXPress++ is an evolving product. Registered owners are given free access to the beta area of our Website. Reported bugs are fixed often and patch files and free updates are posted on our website. You must register your copy of eXPress++ to attain access to these files.<br><br> REPORTING PROBLEMS<br><br> If you encounter a bug in eXpress++, please send an e-mail to support@dclip.com. We can help you much faster if you also include a small program (with source code) that demonstrates the bug or the problem.<br><br> If you have questions about how to use eXpress++ or are confused about documentation, samples, etc. please post your questions on our support forum at http://donnay-software.com. This way, the answers to your questions can be shared with other users of eXpress++. 


FEATURES

Features of eXPress++

* Converts @SAY..GETs to Windows-style dialogs or HTML for Web applications. Supports WHEN, VALID and HIDE clauses.<br><br> * Converts @PROMPT and MENU TO to Windows-style pushbutton menus.<br><br> * Converts AChoice() and DbEdit() to Windows-style browse.<br><br> * Converts SET DEVICE TO PRINT and @SAYs to Windows-style printer commands.<br><br> * Build any complicated GUI dialog or HTML Web page using simple procedural-style commands like this:<br><br> @ <nRow>, <nCol> DCTABPAGE <oGroup> CAPTION <cText><br><br> @ <nRow>, <nCol> DCSAY <cSay> GET <uVar> <OPTIONS><br><br> @ <nRow>, <nCol> DCCHECKBOX <uVar> PROMPT <cPrompt> <OPTIONS><br><br> @ <nRow>, <nCol> DCRADIOBUTTON <uVar> VALUE <xVal> <OPTIONS><br><br> @ <nRow>, <nCol> DCMULTILINE <uVar> <OPTIONS><br><br> @ <nRow>, <nCol> DCLISTBOX <uVar> LIST <aList> <OPTIONS><br><br> @ <nRow>, <nCol> DCCOMBOBOX <uVar> LIST <aList> <OPTIONS><br><br> @ <nRow>, <nCol> DC3STATE <uVar> PROMPT <aVar> <OPTIONS><br><br> @ <nRow>, <nCol> DCSPINBUTTON <nVar> <OPTIONS><br><br> @ <nRow>, <nCol> DCPUSHBUTTON CAPTION <cCaption> ; SIZE <nWidth, nHeight> ACTION <bAction> <OPTIONS><br><br> @ <nRow>, <nCol> DCGROUP <oGroup> CAPTION <cCaption> SIZE <nWidth, nHeight> <OPTIONS><br><br> @ <nRow>, <nCol> DCSTATIC <oStatic> CAPTION <cCaption> SIZE <nWidth, nHeight> <OPTIONS><br><br> DCTOOLBAR <oToolbar> TYPE <nType> <OPTIONS><br><br> DCADDBUTTON CAPTION <cCaption> PARENT <oToobar> ; ACTION <bAction> <OPTIONS><br><br> DCMESSAGEBOX <oMsg> TYPE <nType> <OPTIONS><br><br> DCMENUBAR <oMenuBar> <OPTIONS><br><br> DCSUBMENU <oSubMenu> PROMPT <cPrompt> PARENT <oMenuBar> ; <OPTIONS><br><br> DCMENUITEM PROMPT <cPrompt> PARENT <oSubMenu> ; ACTION <bAction> <OPTIONS><br><br> @ <nRow>, <nCol> DCBROWSE <oBrowse> DATA <aData | cAlias> ; SIZE <nWidth, nHeight> <OPTIONS><br><br> DCBROWSECOL <nbData> HEADER <cHeader> PARENT <oBrowse> <OPTIONS><br><br> DCBITMAP <ncRes> PARENT <oParent> <OPTIONS><br><br> @ <nRow>, <nCol> DCSCROLLBAR DATA <uVar> ; SIZE <nWidth, nHeight> SCROLL <bScroll> <OPTIONS><br><br> @ <nRow>, <nCol> DCPROGRESS <oProgress> ; SIZE <nWidth, nHeight> <OPTIONS><br><br> DCGETOPTIONS WINDOW SIZE <nWidth, nHeight> SAYFONT <cFont> ROWSPACE <nPixels> <OPTIONS><br><br> @ <nRow>, <nCol> DCDIRTREE DIRS <oDirs> VAR <cDirVar> ; DATALINK <bDirLink>] FILES <oFiles> VAR <cFileVar> ; DATALINK <bFileLink> <OPTIONS><br><br> .. more commands<br><br> * Fully compatible with dCLIP++, an application development system for creating data-driven applications. GUI dialogs can be loaded from a data-dictionary.<br><br> * Includes a .DLL for distribution with your Xbase++ applications and .LIB files to link the .DLL to your application with either ALINK or BLINKER 5.0<br><br> * Includes all source code.<br><br> * Includes a full set of sample programs to make it easy to get started.<br><br> * Complete on-line documentation in Windows .HLP format.<br><br> * Includes Clipper .MEM file conversion utility.<br><br> * Includes a set of Scoping functions to make it easier to migrate Clipper applications using RDDs that support scoping like SX_SetScope(), CMXSetScope, CMXSetRelation(), AX_SetScope(), etc.<br><br> * Upgrades and patches available on World-Wide-Web.<br><br> * Unlimited Free Technical support<br><br> 


README.TXT

The README.TXT file

The text file titled README.TXT is located in the root of the installation directory and contains information about any late developments, additions, or changes that did not make it into the printed documentation. It also contains a complete history of changes since version 1.0. Please read this file before using eXpress++. It is an ordinary text file you can view with any text editor, word processor, or the DOS command: TYPE README.TXT. To PRINT the README.TXT file use the following DOS command: COPY README.TXT PRN. 


GENERAL LICENSE

Your eXPress++ License

1. You MAY freely distribute any .EXEcutable application that uses any portion of the dXPress libraries and/or the eXPress++ .DLLs in your own custom applications.<br><br> 2, You MAY freely distribute the DCLIP*.DLL files with your applications.<br><br> 3. You MAY NOT distribute to any third party, any portion of the eXPress++ source code.<br><br> 4. You MAY use the eXpress++ libraries on only one computer at a time for each license that is owned. The eXPress++ libraries or eXPress++ .DLLs may be installed on a network server for shared use by multiple programmers, however, it is not allowed that there be more users of the product at any one time than the number of paid licenses. 


FAQ

Frequently Asked Questions

Q. Is DCDIALOG.CH a superset or a different (and larger) set from EXPRESS.CH ? If I include DCDIALOG.CH, is there no need to also include EXPRESS.CH ? Is there a minimum set of include files I need in order to have all eXPress++ commands available to me when coding an application?<br><br>A. EXPRESS.CH is only recommended if you want to convert existing Clipper @SAY..GETs without changing any code. It is highly recommended that you _NEVER_ use EXPRESS.CH but instead get used to using DCDIALOG.CH. This is a much more robust command set however, it does require that you change @SAY..GET commands to @DCSAY..GET commands. For most applications, only DCDIALOG.CH is required, however, if you are using eXPress++ printer commands you must include DCPRINT.CH and if you are using less popular commands like DCDIR or DCAPPEDIT you must include DCDIR.CH and DCAPP.CH respectively. The documentation for each command also contains info about the .CH file that contains the command.<br><br>-------------------------------------------------------------------<br><br>Q. In sample code, I notice that GetList and GetOptions variables should be initialized (before using the get reader). There seems to be an inconsistency in that GetOptions is initialized simply to NIL (that is, no value is assigned), whereas GetList is initialized to an empty array. <br><br>A. The GetList array must be initialized to an empty array because each DC* command "adds" an element to the GetList array. GetOptions should be initialized to a NIL only out of convention because, in the event that the GET OPTIONS command is not used yet the GetOptions variable is passed to DC_ReadGui(), it must be either a NIL or a valid GetOptions array. Anything else may create a runtime error. The GET OPTIONS command creates a valid array from the arguments used with the command.<br><br>-------------------------------------------------------------------<br><br>Q. Is "GUI ON" or DC_Gui(.t.) actually needed when using DCDIALOG.CH ?<br><br>A. Most DCDIALOG.CH commands simply add information about objects to a GetList which will be processed later via the DC_ReadGUI() or DC_ReadGets() function. When using the DCREAD GUI command or DC_ReadGUI() function, the GetList will be processed via the GUI reader regardless of the state of DC_Gui(). When using the DCREAD command or the DC_ReadGets() function, the GetList is processed by the text reader when DC_Gui() is .FALSE. or by the GUI reader when DC_Gui() is .TRUE. It is highly recommended that applications be created an converted to work in GUI mode only. Dual-Mode is provided only for quick conversion of existing Clipper code. Once the programmer realizes how many more features are available in GUI mode, using the GUI reader will become second-nature. If the end result is to create a full-GUI application, then set DC_Gui(.T.) and the beginning of the application and never change it.<br><br>-------------------------------------------------------------------<br><br>Q. After creating all my objects with DC* commands, I want to make sure that DCREAD GUI sets the focus to a specified object on a specified Tab Page before entering the event loop. How do I do that?<br><br>A. The DCREAD GUI command supports an EVAL clause. The code-block associated with this clause will be evaluated just before the GUI reader enters its event loop. Use this code-block to accomplish any task which cannot be done until all the objects have been created. Example:<br><br> DCREAD GUI EVAL {||SetAppFocus(oTabPage3), SetAppFocus(oBrowse)} An additional method is to use the SETFOCUS <oObject> clause in the DCREAD GUI comand.<br><br>-------------------------------------------------------------------<br><br>Q. I want to use DCREAD GUI to add objects to an existing XbpDialog parent that already has other objects and then destroy those objects when returning from the GUI reader without touching previously created objects.<br><br>A. Use the desired DC* commands to add the objects to the GetList, then pass the GetList and the parent object to the GUI reader. After exiting the GUI reader, destroy the objects with the DC_GetDestroy() function. Example:<br><br> LOCAL GetList := {}<br><br> // Add all objects here<br><br> DCREAD GUI PARENT @oDialog DC_GetDestroy(GetList)<br><br>----------------------------------------------------------------------<br><br>Q. My Browses sometimes fail to display headers and/or scrollbars. What do I do?<br><br>A. This is an anomoly in Xbase++ caused by adding XbpColumn objects to an XbpBrowse object when the XbpBrowse is visible. The browse will repaint itself properly simply by hiding and showing it again. The EVAL clause of DCREAD GUI can be used to resolve this problem like so:<br><br> DCREAD GUI EVAL {||oBrowse:hide(), oBrowse:show()}<br><br>----------------------------------------------------------------------<br><br>Q. DC_ReadGUI() gives me an error when browsing an empty array.<br><br>A. At the present time, there is no solution to this problem. Make sure that there is at least one element in any array that is being browsed.<br><br>----------------------------------------------------------------------<br><br>Q. My date pictures are not working properly in some of my GETS. I give it a picture clause of '99/99/9999' but still get only a display of '99/99/99'<br><br>A. Make sure to use the SET DATE FORMAT command to set the date format for 10 characters. Ex: SET DATE FORMAT TO "mm/dd/yyyy".<br><br>----------------------------------------------------------------------<br><br>Q. Is it possible to reference the getlist within a function, within a valid clause e.g. I need to know which get I am on i.e. the 1st get or 2nd get and use this to operate things in my function.<br><br>A. Yes. The GetList can be referenced in any code block and used later in validation routines, navigation routines, etc.. It isn't usually necessary to pass the GetList however, because a pointer to the GetList is stored in :cargo for each object in the GetList. The :cargo instance variable contains an array of at least three (3) elements. The first element of :cargo is the element number of the GetList that contains all the information about the object. The second element is a pointer to the GetList array. The third element is whatever value was stored in CARGO in the GetList with the CARGO <xCargo> option. If you have a pointer to the object then you can always get a pointer to the GetList. Conversely, if you have a pointer to the GetList, you can get a pointer to the object because the object is stored in GetList[ <nGetNumber>, oGETLIST_OBJECT] ).<br><br>---------------------------------------------------------------------- <br><br>Q. What is the EVAL clause used for on DC* commands? Is this option something for us to manipulate? If so what?<br><br>A. EVAL is used to evaluate any code-block immediately AFTER the object is created by DC_ReadGUI(). When DC_ReadGUI() reads the GetList, it creates the object based on all the passed options for that object. Before continuing on to the next item in the GetList, it is sometimes desirable to call a special function to handle some special circumstance for the object that was just created. A pointer to the object is passed to the code-block.<br><br> The Get-List array is designed to handle only the most commonly used options for an object like VISIBLE, HIDE, CURSOR, TABSTOP, COLORS, LOCATIONS, SIZES, etc. There are many classes that support other features that may be desirable to enable or change.<br><br> Look at the DCMULTILINE example in XDEMO1.PRG. You'll see how the EVAL clause is used to store a code block into the :rbdown callback slot so the right button will popup a special menu.<br><br> @ 5,2 DCMULTILINE cMemo PARENT oTabPage3 SIZE 78,8 ; TITLE 'MULTLINE History Memo' ; TABSTOP ; FONT "10.Courier" ; OBJECT oMemo ; EVAL { |o| o:RbDown := { |x,y,z| oMenuMemo:PopUp ( z, x, 2 ,; XBPMENU_PU_DEFAULT + XBPMENU_PU_MOUSE_RBDOWN ) } }<br><br>------------------------------------------------------------------<br><br>Q. How do I get dialog messages on buttons like OK and CANCEL to display in GERMAN?<br><br>A. Add a call to DC_LangSet('GERMAN') at the beginning of your program.<br><br>------------------------------------------------------------------<br><br>Q. Why does the COLOR clause not work on most DC* commands?<br><br> Win32 - Windows supports the definition of a foreground color only for XbpDialog:drawingArea, XbpStatic(), XbpBrowse() and all classes derived from XbpSetting(). <br><br> eXPress++ was written entirely in Xbase++ code, thereby offering source compatability with the Windows, OS/2 and all future OS's supported by Alaska. The COLOR clause was included on all commands for future compatability even though it may not be compatabile with the current version of Windows.<br><br>------------------------------------------------------------------<br><br>Q. Is there a recommended order for placement of the commands? I am building a complex screen with many tabs, subtabs, browses, and other DC* commands. Sometimes they do not work as expected in one order, but do in another.<br><br>A. Commands which reference a PARENT object must always come AFTER the creation of the PARENT object. This is basically the same rule as when programming completely object-oriented. A PARENT object cannot be referenced if it does not exist. Basically, objects get created in the order they appear in the GetList array, so parent objects must be created first. For example, a DCTABPAGE command must come before an @DCSAY..GET command which uses the TabPage as it's parent. <br><br>------------------------------------------------------------------<br><br>Q. I am having difficulty getting MODAL popup windows to work correctly. If the first MODAL window has a button that invokes a second MODAL window, clicking back on the first window causes a lockup condition.<br><br>A. For MODAL windows to function properly, the calling window must be the SetAppWindow(). This can be accomplished quite easily by using the EVAL clause of the DCREAD GUI command like so:<br><br> DCREAD GUI ; FIT ; ADDBUTTONS ; MODAL ; EVAL {|o|SetAppWindow(o)}<br><br>------------------------------------------------------------------<br><br>Q. How do I create a button to exit the DCREAD GUI event loop and close the dialog window.<br><br>A. Use the DC_ReadGuiEvent() function like so:<br><br> @ 10,10 DCPUSHBUTTON CAPTION 'Ok' ; SIZE 10,2 ACTION {||DC_ReadGuiEvent(DCGUI_EXIT_OK)}<br><br> @ 10,30 DCPUSHBUTTON CAPTION 'Cancel' ; SIZE 10,2 ACTION {||DC_ReadGuiEvent(DCGUI_EXIT_ABORT)}<br><br>------------------------------------------------------------------<br><br>Q. Why do my source code files compile so slow when I use a lot of eXPress++ commands?<br><br>A. The Xbase++ pre-processor works overtime when converting the eXPress++ commands to equivalent functions. Most of the commands build a large array of properties which are added to the GetList. This is a time-intensive process, especially when compiling to COFF format .OBJ files. Blinker 5.1 allows for linking of OMF format .OBJ files. The XPP.EXE compiler runs from 5 to 10 times faster when compiling with the /OMF switch. Upgrading to Blinker 5.1 can save considerable time in compiling and linking. It also supports multiple resource files. 


PDR

Problem Reports


CONVERTING @..SAYS

Converting @SAYS from text to GUI

Working with @..SAYS is not as straight forward as working with AChoice() or Dbedit() because @..SAYS usually used in Clipper applications for a variety of screen functions. For example, it is not possible to create a GUI conversion system that can convert any text-based screen to a GUI-based dialogue because the conversion program simply cannot decipher the "intent" of the programmer by looking at either the code or the screen.<br><br> It is possible, however, to break down some @SAY scenarios into pieces that can be managed with Dual-Mode functions.<br><br> Let's look at the following Clipper @SAY scenario:<br><br> We want to display a series of messages on the screen as we are progressing through the updating of a database structure. The original Clipper source code might look something like this:<br><br> cScreen := SaveScreen( 3,5,16,50 ) @ 3,5 TO 16,50 @ 4,6 CLEAR TO 15,49 @ 6,10 SAY 'Creating Backup..' Backup() @ 8,10 SAY 'Copying Structure ..' CopyStru() @ 10,10 SAY 'Modifying Structure..' ModiStru() @ 12,10 SAY 'Appending from Backup..' AppendBack() @ 14,10 SAY 'Done! Press any key to continue' Inkey(0) RestScreen( 3,5,14,75,cScreen) <br><br> The above code can be easily modified to Dual-Mode because the @..SAYS are organized in a "window" area of the screen and because they are simply status messages which are displayed during the progress of the program. To accomplish this task we use the Dual-Mode functions: DC_EXPL(), DC_IMPL() DC_SAY(), and DC_CLS() or the Dual-Mode commands: DCEXPLODE, DCIMPLODE, @..SAYWIN, and CLS (contained in EXPRESS.CH).<br><br> The command DCEXPLODE paints a box on the screen and returns an array of information about this new "object" which includes saved screen contents (in TEXT mode) or a reference to a Dialog object (in GUI mode). @..SAYWIN is translated in EXPRESS.CH to paint the says on the parent object. If no parent object is included in the @..SAYWIN command, then the last object created by DCEXPLODE is assumed to be the parent, otherwise the full screen is used as the parent. If the GUI flag is on, then the screen object will be a GUI dialog box. The command DCIMPLODE is used to restore the screen area (in Text mode) or destroy the parent dialogue object (in GUI mode).<br><br> /* ----------------------- */<br><br> #include "express.ch"<br><br> FUNCTION XTest()<br><br> LOCAL aScreen<br><br> GUI ON // turn on GUI mode<br><br> @ 3, 5, 16, 50 DCEXPLODE aScreen FONT "10.courier"<br><br> @ 2,5 SAYWIN 'Creating Backup..' DC_Pause(1) Backup()<br><br> @ 4,5 SAYWIN 'Copying Structure ..' DC_Pause(1) CopyStru()<br><br> @ 6,5 SAYWIN 'Modifying Structure..' DC_Pause(1) ModiStru()<br><br> @ 8,5 SAYWIN 'Appending from Backup..' DC_Pause(1) AppendBack()<br><br> DCIMPLODE aScreen<br><br> RETURN nil<br><br> /* ----------------------- */<br><br> NOTE: These examples are here for general guidelines on how to approach the conversion of existing code to GUI, not because it is a recommended method of application conversion. After studying the examples in \express\sample by running XDEMO.EXE, it will become more clear on how to approach the conversion of your application to GUI. EXPRESS.CH is a very simplistic approach to understanding how the preprocessor can be used in a variety of ways to create a command interface to Xbase++ parts which resembles or closely emulates Clipper text- based syntax. The recommended approach to converting Clipper applications is to study DCDIALOG.CH and the DC* commands. This is a much more robust command set specifically designed to produce a full GUI application that is easy to write and maintain.<br><br>

Files:

EXPRESS.CH, DCDIALOG.CH

See Also:

   dc_expl()
   dc_say()


CONVERTING ACHOICE()

Converting ACHOICE() from text to GUI

Let's look at the following Clipper ACHOICE() scenario:<br><br> We have a field list which we want to browse on the screen by first saving a screen area, painting a box on the screen, creating an ACHOICE() pick-list in the the boxed area, choosing a field, then restoring the original screen. The original code might look something like this:<br><br> FUNCTION Xtest()<br><br> LOCAL cScreen, aFields, nField<br><br> cScreen := SaveScreen( 3,5,20,25 ) @ 3,5 TO 20,25 @ 4,6 CLEAR TO 19,24 USE COLLECT aFields := Array(Fcount()) AFields(aFields) nField := AChoice( 4, 6, 19, 24, aFields ) RestScreen( 3,5,14,25,cScreen)<br><br> RETURN nField<br><br> /* --------------------- */<br><br> Now we want to change the code to display the same Browse in a Windows GUI dialogue box:<br><br> FUNCTION Xtest()<br><br> #include "express.ch"<br><br> LOCAL aFields, nField<br><br> * cScreen := SaveScreen( 3,5,20,25 ) // this isn't needed * @ 3,5 TO 20,25 // this isn't needed * @ 4,6 CLEAR TO 13,74 // this isn't needed GUI ON // turn on GUI mode USE COLLECT aFields := Array(Fcount()) AFields(aFields) nField := AChoice( 4, 6, 19, 24, aFields ) * RestScreen( 3,5,14,25,cScreen) // this isn't needed<br><br> RETURN nField<br><br> /* -------------- */<br><br> That's all there is to it. "express.ch" translates the ACHOICE() function to call DC_ACHOICE() which is a Dual-Mode function.<br><br>

Files:

EXPRESS.CH

See Also:

   dc_achoice()


CONVERTING DBEDIT()

Converting DBEDIT() from text to GUI

Let's look at the following Clipper DBEDIT() scenario:<br><br> We have a database which we want to browse on the screen by first saving a screen area, painting a box on the screen, creating an DBEDIT() browse in the the boxed area, choosing a field, then restoring the original screen. The original code might look something like this:<br><br> FUNCTION Xtest1()<br><br> LOCAL cScreen<br><br> cScreen := SaveScreen( 3,5,20,75 ) @ 3,5 TO 20,75 @ 4,6 CLEAR TO 19,74 USE COLLECT VIA DBFNTX DbEdit( 4, 6, 19, 74 ) RestScreen( 3,5,14,75,cScreen)<br><br> RETURN nil<br><br> /* ---------------------- */<br><br> Now we want to change the code to display the same Browse in a Windows GUI dialogue box:<br><br> FUNCTION XTest2()<br><br> #include "express.ch"<br><br> * cScreen := SaveScreen( 3,5,20,75 ) // this isn't needed * @ 3,5 TO 20,75 // this isn't needed * @ 4,6 CLEAR TO 13,74 // this isn't needed GUI ON // turn on GUI mode USE COLLECT VIA DBFNTX DbEdit( 4, 6, 19, 74 ) * RestScreen( 3,5,14,75,cScreen) // this isn't needed<br><br> RETURN nil<br><br> /* ------------------ */<br><br> That's all there is to it. "express.ch" translates the DBEDIT() function to call DC_DBEDIT() which is a Dual-Mode function.<br><br>

Files:

EXPRESS.CH

See Also:

   dc_dbedit()


CONVERTING GETS

Converting @SAY..GETS from text to GUI

Let's look at the following Clipper @SAY..GET scenario:<br><br> We have a table of GETS which we want to display on the screen by first saving a screen area, painting a box on the screen, writing all the GETS in the boxed area, editing the gets, then restoring the original screen. The code might look something like this:<br><br> FUNCTION Xtest1()<br><br> LOCAL GetList, cLastName := Space(15), cFirstName := Space(15), ; cCompany := Space(30), cStreet := Space(30), cCity := Space(25), ; cState := Space(10), cCountry := Space(20), cPhone := Space(12), ; cScreen<br><br> cScreen := SaveScreen( 3,5,14,75 ) @ 4,6 CLEAR TO 13,74 GetList := {} @ 5,10 SAY ' Last Name' GET cLastName VALID !Empty(cLastName) @ 5,40 SAY 'First Name' GET cFirstName VALID !Empty(cFirstName) @ 7,10 SAY ' Company' GET cCompany @ 8,10 SAY ' Street' GET cStreet VALID !Empty(cStreet) @ 9,10 SAY ' City' GET cCity VALID !Empty(cCity) @10,10 SAY ' State' GET cState PICT '@!' ; VALID StateValid(cState) @10,40 SAY ' Country' GET cCountry PICT '@!' ; VALID CountryValid(cCountry) @12,40 SAY ' Phone' GET cPhone PICT '(999)-999-9999' READ RestScreen( 3,5,14,75,cScreen)<br><br> RETURN nil<br><br> /* ------------------------- */<br><br> STATIC FUNCTION StateValid(cState)<br><br> IF !( ' ' + Alltrim(cState) $ ' AL AK AZ CA MI MN NY NSW ' ) DC_MsgBox('State must be AK, AK, AZ, CA, MI, MN, NY or NSW') RETURN .f. ENDIF RETURN .t.<br><br> /* ------------------------- */<br><br> STATIC FUNCTION CountryValid(cCountry)<br><br> IF !( ' ' + Alltrim(cCountry) $ ' USA CANADA GERMANY ' ) DC_MsgBox('Country must be USA, CANADA or GERMANY') RETURN .f. ENDIF RETURN .t.<br><br> /* -------------------------- */<br><br> Now we want to change the code to display the same GETS in a Windows GUI dialogue box: FUNCTION Xtest2()<br><br> #include "express.ch"<br><br> LOCAL GetList, cLastName := Space(15), cFirstName := Space(15), ; cCompany := Space(30), cStreet := Space(30), cCity := Space(25), ; cState := Space(10), cCountry := Space(20), cPhone := Space(12)<br><br> * cScreen := SaveScreen( 3,5,14,75 ) // this isn't needed * @ 4,6 CLEAR TO 13,74 // this isn't needed GUI ON // turn on GUI mode GetList := {} @ 5,10 SAY ' Last Name' GET cLastName VALID !Empty(cLastName) @ 5,40 SAY 'First Name' GET cFirstName VALID !Empty(cFirstName) @ 7,10 SAY ' Company' GET cCompany @ 8,10 SAY ' Street' GET cStreet VALID !Empty(cStreet) @ 9,10 SAY ' City' GET cCity VALID !Empty(cCity) @10,10 SAY ' State' GET cState PICT '@!' ; VALID StateValid(cState) @10,40 SAY ' Country' GET cCountry PICT '@!' ; VALID CountryValid(cCountry) @12,40 SAY ' Phone' GET cPhone PICT '(999)-999-9999' READ * RestScreen( 3,5,14,75,cScreen) // this isn't needed<br><br> RETURN nil<br><br> That's all there is to it. "express.ch" translates the @SAY..GETS so that they add a new kind of object to the Getlist array and it translates the READ command so it passes the Getlist array to DC_ReadGui() instead of ReadModal().<br><br> NOTE: These examples are here for general guidelines on how to approach the conversion of existing code to GUI, not because it is a recommended method of application conversion. After studying the examples in \express\sample by running XDEMO.EXE, it will become more clear on how to approach the conversion of your application to GUI. EXPRESS.CH is a very simplistic approach to understanding how the preprocessor can be used in a variety of ways to create a command interface to Xbase++ parts which resembles or closely emulates Clipper text- based syntax. The recommended approach to converting Clipper applications is to study DCDIALOG.CH and the DC* commands. This is a much more robust command set specifically designed to produce a full GUI application that is easy to write and maintain.<br><br><br><br><br><br>

Files:

DCDIALOG.CH, EXPRESS.CH

See Also:

   DCREAD GUI
   dc_readgui()


CONVERTING MEMOEDIT()

Converting MEMOEDIT() from text to GUI

Let's look at the following Clipper MemoEdit() scenario:<br><br> We have a memo which we want to edit on the screen by first saving a screen area, painting a box on the screen, running the Memo Editor, then restoring the original screen. The code might look something like this:<br><br> FUNCTION Xtest1()<br><br> LOCAL cScreen, cMemo<br><br> cScreen := SaveScreen( 5,5,20,75 ) @ 5,5 CLEAR TO 20,75 @ 5,5 TO 20,75 DOUBLE<br><br> cMemo := MemoRead('README.TXT')<br><br> cMemo := MemoEdit(cMemo,6,6,19,74)<br><br> MemoWrit( 'README.TXT', cMemo )<br><br> RestScreen( 8,5,20,75,cScreen)<br><br> RETURN cMemo<br><br> /* ----------------------- */<br><br> Now we want to change the code to display the memo editor in a Windows GUI dialogue box: <br><br> FUNCTION Xtest2()<br><br> #include "express.ch"<br><br> LOCAL cScreen, cMemo<br><br> GUI ON // turn on GUI mode * cScreen := SaveScreen( 5,5,20,75 ) this is not needed * @ 5,5 CLEAR TO 20,75 this is not needed * @ 5,5 TO 20,75 DOUBLE this is not needed<br><br> cMemo := MemoRead('README.TXT')<br><br> cMemo := MemoEdit(cMemo,6,6,19,74)<br><br> MemoWrit( 'README.TXT', cMemo )<br><br> * RestScreen( 8,5,20,75,cScreen) this is not needed<br><br> RETURN cMemo<br><br> /* ------------------ */<br><br> That's all there is to it. "express.ch" translates the MEMOEDIT() function to call DC_MEMOEDIT() which is a Dual-Mode function.

Files:

EXPRESS.CH

See Also:


CONVERTING MENUS

Converting @PROMPT menus from text to GUI

Let's look at the following Clipper Menu scenario:<br><br> We have a menu which we want to display on the screen by first saving a screen area, painting a box on the screen, writing all the menu PROMPTS in the boxed area, running the menu, then restoring the original screen. The code might look something like this:<br><br> FUNCTION Xtest1()<br><br> LOCAL cScreen, PromptList, nChoice<br><br> cScreen := SaveScreen( 8,5,16,75 ) @ 8,5 CLEAR TO 16,75 @ 8,5 TO 15,75 DOUBLE PromptList := {} SET WRAP ON SET MESSAGE TO 16 CENTER<br><br> @ 10,10 PROMPT ' Enter New Names ' ; MESSAGE 'Add new names and addresses' @ 11,10 PROMPT ' Print List ' ; MESSAGE 'Print the Customer List' @ 12,10 PROMPT ' Dial ' ; MESSAGE 'Dial customers starting at top of list' @ 13,10 PROMPT ' Import ' ; MESSAGE 'Import a new Customer List'<br><br> @ 10,40 PROMPT ' Manager ' ; MESSAGE 'Run the Database Manager' @ 11,40 PROMPT ' Calendar ' ; MESSAGE 'Check the Appointment Schedule' @ 12,40 PROMPT ' Purge ' ; MESSAGE 'Remove all the dialed numbers from the list' @ 13,40 PROMPT ' Exit ' ; MESSAGE 'Quit the program'<br><br> MENU TO nChoice RestScreen( 8,5,16,75,cScreen)<br><br> RETURN nChoice<br><br> /* ----------------------- */<br><br> Now we want to change the code to display the same PROMPTS in a Windows GUI dialogue box:<br><br> FUNCTION Xtest2()<br><br> LOCAL PromptList, nChoice<br><br> #include "express.ch"<br><br> * cScreen := SaveScreen( 3,5,15,75 ) // don't need this * @ 3,5 TO 15,75 DOUBLE // don't need this * @ 4,6 CLEAR TO 14,74 // don't need this PromptList := {} SET WRAP ON SET MESSAGE TO 16 CENTER GUI ON // turn on GUI<br><br> @ 10,10 PROMPT ' Enter New Names ' ; MESSAGE 'Add new names and addresses' @ 11,10 PROMPT ' Print List ' ; MESSAGE 'Print the Customer List' @ 12,10 PROMPT ' Dial ' ; MESSAGE 'Dial customers starting at top of list' @ 13,10 PROMPT ' Import ' ; MESSAGE 'Import a new Customer List'<br><br> @ 10,40 PROMPT ' Manager ' ; MESSAGE 'Run the Database Manager' @ 11,40 PROMPT ' Calendar ' ; MESSAGE 'Check the Appointment Schedule' @ 12,40 PROMPT ' Purge ' ; MESSAGE 'Remove all the dialed numbers from the list' @ 13,40 PROMPT ' Exit ' ; MESSAGE 'Quit the program'<br><br> MENU TO nChoice<br><br> * RestScreen( 3,5,15,75,cScreen) // don't need this<br><br> RETURN nChoice<br><br> /* --------------------- */<br><br> That's all there is to it. "express.ch" translates the @PROMPTS so that they add a new kind of object to the PromptList array and it translates the MENU TO command so it passes the PromptList array to DC_MenuTo() instead of _MenuTo().<br><br> NOTE: These examples are here for general guidelines on how to approach the conversion of existing code to GUI, not because it is a recommended method of application conversion. After studying the examples in \express\sample by running XDEMO.EXE, it will become more clear on how to approach the conversion of your application to GUI. EXPRESS.CH is a very simplistic approach to understanding how the preprocessor can be used in a variety of ways to create a command interface to Xbase++ parts which resembles or closely emulates Clipper text- based syntax. The recommended approach to converting Clipper applications is to study DCDIALOG.CH and the DC* commands. This is a much more robust command set specifically designed to produce a full GUI application that is easy to write and maintain.<br><br><br><br>

Files:

EXPRESS.CH

See Also:

   dc_menu_to()


CONVERTING PRINT

Converting Printer @..SAYS

Let's look at the following Clipper Print @..SAY scenario:<br><br> We have a columnar report in which we want to give the user the option of choosing a printer, such as a network printer or a fax, a starting and ending page, a font, and the number of rows and columns on the paper.<br><br> The original Clipper report looks like this:<br><br> FUNCTION MyReport ( nCopies )<br><br> LOCAL nRow, nSaveRec, cScrn, aFor_Sale, i, nPage<br><br> SELE collect nSaveRec := RecNo() GO TOP<br><br> aFor_Sale := { 'No','Yes','Not Sure' }<br><br> SET DEVICE TO PRINT<br><br> cScrn := DC_WaitOn('Printing..')<br><br> FOR i := 1 TO nCopies<br><br> GO TOP nRow := 1 nPage := 1 DO WHILE !Eof() IF nRow = 1<br><br> @ nRow,10 SAY 'My Personal Collection Inventory' @ nRow,50 SAY 'Page ' + Alltrim(Str(nPage)) @ nRow,70 SAY Date()<br><br> nRow += 2<br><br> @ nRow,0 SAY 'Description' @ nRow,35 SAY 'Type' @ nRow,50 SAY 'Sub-Type' @ nRow,65 SAY 'Cond' @ nRow,71 SAY 'For Sale?' @ nRow,82 SAY 'Value' nRow += 2<br><br> ELSE @ nRow,0 SAY COLLECT->descrip @ nRow,35 SAY COLLECT->type @ nRow,50 SAY COLLECT->sub_type @ nRow,65 SAY COLLECT->condition @ nRow,71 SAY aFor_Sale[COLLECT->for_sale+1] @ nRow,82 SAY Str(COLLECT->appr_value,7,2) nRow++<br><br> SKIP<br><br> IF nRow > 60 EJECT nRow := 1 ENDIF ENDIF ENDDO<br><br> NEXT<br><br> SET DEVICE TO SCREEN DC_Impl(cScrn)<br><br> GO nSaveRec RETURN nil<br><br> -----------------------------------------------------------<br><br> The modified report looks like this:<br><br> #include "DCPRINT.CH"<br><br> FUNCTION MyReport ( )<br><br> LOCAL nRow, nSaveRec, cScrn, aFor_Sale, oPrinter, i, nPage<br><br> SELE collect nSaveRec := RecNo() GO TOP<br><br> aFor_Sale := { 'No','Yes','Not Sure' }<br><br> BEGIN SEQUENCE<br><br> DCPRINT ON TO oPrinter // Pop-Up printer dialog<br><br> cScrn := DC_WaitOn('Printing..')<br><br> FOR i := 1 TO oPrinter:nCopies<br><br> GO TOP nRow := 1 oPrinter:nPage := 1<br><br> DO WHILE !Eof() IF nRow = 1<br><br> @ nRow,10 DCPRINT SAY 'My Personal Collection Inventory' @ nRow,50 DCPRINT SAY 'Page ' + Alltrim(Str(oPrinter:nPage)) @ nRow,70 DCPRINT SAY Date()<br><br> nRow += 2<br><br> @ nRow,0 DCPRINT SAY 'Description' @ nRow,35 DCPRINT SAY 'Type' @ nRow,50 DCPRINT SAY 'Sub-Type' @ nRow,65 DCPRINT SAY 'Cond' @ nRow,71 DCPRINT SAY 'For Sale?' @ nRow,82 DCPRINT SAY 'Value' nRow += 2<br><br> ELSE @ nRow,0 DCPRINT SAY COLLECT->descrip @ nRow,35 DCPRINT SAY COLLECT->type @ nRow,50 DCPRINT SAY COLLECT->sub_type @ nRow,65 DCPRINT SAY COLLECT->condition @ nRow,71 DCPRINT SAY aFor_Sale[COLLECT->for_sale+1] @ nRow,82 DCPRINT SAY Str(COLLECT->appr_value,7,2) nRow++<br><br> SKIP<br><br> IF nRow > ( oPrinter:nRows - 5 ) DCPRINT EJECT nRow := 1 ENDIF ENDIF ENDDO<br><br> NEXT<br><br> END SEQUENCE<br><br> DCPRINT OFF DC_Impl(cScrn)<br><br> GO nSaveRec RETURN nil<br><br> The structure of the report does not change. Only the syntax of a few commands are required to change like so:<br><br> From To --------------------------- ------------------------------------ SET DEVICE TO PRINT DCPRINT ON [ TO <oPrinter> ] SET PRINT ON DCPRINT ON [ TO <oPrinter> ] @ <nRow>,<nCol> SAY <cText> @ <nRow>,<nCol> DCPRINT SAY <cText> EJECT DCPRINT EJECT SET DEVICE TO SCREEN DCPRINT OFF ?/?? <cText> DCPRINT ?/?? <cText><br><br> Additional commands can then be added to the report to improve the output like so:<br><br> DCPRINT FONT <cFontName> @ <nSrow>,<nSCol>,<nERow>,<nECol> DCPRINT BOX <OPTIONS> @ <nSrow>,<nSCol>,<nERow>,<nECol> DCPRINT BITMAP <cBitMap><br><br>

Files:

DCPRINT.CH


LIBRARIES

A brief description of the eXPress++ libraries

DCLIPX.LIB <br><br> This library contains the exported symbols that are in the DCLIPX.DLL dynamic library. Link this library with your application when using any DC_*(), ADS() or AX*() functions in your application.<br><br> DCHELP.LIB This library contains the exported symbols that are in the DCHELP.DLL dynamic library. Link this library with your application when using the DC_Help*() functions in your application.<br><br> DCLIP1.LIB <br><br> This library contains the exported symbols that are in the DCLIP1.DLL dynamic library. Link this library with your application when using DC_Dot() or any DC_*() functions in your application that refer to DCLIP1.DLL in the documentation.<br><br> DCLIP2.LIB <br><br> This library contains the exported symbols that are in the DCLIP2.DLL dynamic library. Link this library with your application when using DC_Dot() or any DC_*() functions in your application that refer to DCLIP2.DLL in the documentation.<br><br> EXPRESS.RES <br><br> This library contains the bitmap, pointer and icon resources used by eXPress++. Link this library with your application when using any DC_*() functions in your application. <br><br> NOTE: ALINK.EXE allows only one (1) .RES file to be linked to an .EXE. If you have your own resources in a .RES file, then you must either add the resources in EXPRESS.EXE to your own .RES file or use Blinker 5.1 which allows for multiple .RES files.<br><br> DCLIPX.DLL <br><br> This is the dynamic-link library that contains all the eXPress++ and Advantage Server functions. It must be distributed with your application.<br><br> DCHELP.DLL <br><br> The is the dynamic-link library that contains the help system based on the DC_Help*() functions. It must be distributed with your application.<br><br> DCLIP1.DLL <br><br> This is the dynamic-link library that contains DC_Dot() and most of its supporting functions. It must be distributed with your application if the app contains functions referencing DCLIP1.DLL in the documentation.<br><br> DCLIP2.DLL <br><br> This is the dynamic-link library that contains DC_Dot() and most of its supporting functions. It must be distributed with your application if the app contains functions referencing DCLIP2.DLL in the documentation.<br><br> JACP31XP.DLL and JACE31.DLL <br><br> These are the JazzAge 3.1 runtime DLLs. They are used with eXpress++ functions that require ActiveX support such as DC_Help() and DC_PrintPreviewAcrobat(). They are only needed when using Xbase++ versions 1.82 or earlier. <br><br>

Notes:

DCLIP*.LIB files, by default, are created for compatability with the ALINK.EXE linker. These are COFF format. OMF versions of the DCLIP*.LIB files are contained in the \OMF subdirectory under the \LIB subdirectory of your eXPress++ installation. 


DCLIP1.DLL

The eXpress++ dynamic-link library 1 of 2

The DCLIP1.DLL file is a "dynamic-library" that can be used with Xbase++ applications at runtime. DCLIP1.DLL can be linked to an application either "statically" or "dynamically". It is recommended that Xbase++ .DLLs be linked statically to applications and this requires including DCLIP1.LIB (Alink) or DCLIP1B.LIB (Blinker) in your application link script. By linking a .DLL statically, the .DLL will automatically be opened when the application is started and the symbols will be resolved at link time rather than at load time. This will insure that calls to functions in DCLIP1.DLL do not need to be used in macros, but that they can be used in your code like any other Xbase++ function. DCLIP1.DLL contains approximately half of the version 2.0 functions. The remaining version 2.0 functions are contained in DCLIP2.DLL.<br><br> NOTE: When using DCLIP1.DLL with your Xbase++ applications, you only need to distribute the DCLIP2,DLL, DCLIPX.DLL and DCLIPS.DLL files with the application files. No other files are needed.<br><br>

Files:

DCLIP1.DLL

See Also:

   DCLIP2.DLL


DCLIP2.DLL

The eXpress++ dynamic-link library 2 of 2

The DCLIP2.DLL file is a "dynamic-library" that can be used with Xbase++ applications at runtime. DCLIP2.DLL can be linked to an application either "statically" or "dynamically". It is recommended that Xbase++ .DLLs be linked statically to applications and this requires including DCLIP2.LIB (Alink) or DCLIP2B.LIB (Blinker) in your application link script. By linking a .DLL statically, the .DLL will automatically be opened when the application is started and the symbols will be resolved at link time rather than at load time. This will insure that calls to functions in DCLIP2.DLL do not need to be used in macros, but that they can be used in your code like any other Xbase++ function. DCLIP2.DLL contains approximately half of the version 2.0 functions. The remaining version 2.0 functions are contained in DCLIP1.DLL.<br><br> NOTE: When using DCLIP2.DLL with your Xbase++ applications, you only need to distribute the DCLIP1,DLL, DCLIPX.DLL and DCLIPS.DLL files with the application files. No other files are needed.<br><br>

Files:

DCLIP2.DLL

See Also:

   DCLIP1.DLL


DCLIPX.DLL

The eXpress++ dynamic-link library

The DCLIPX.DLL file is a "dynamic-library" that can be used with Xbase++ applications at runtime. DCLIPX.DLL can be linked to an application either "statically" or "dynamically". It is recommended that Xbase++ .DLLs be linked statically to applications and this requires including DCLIPX.LIB (Alink) or DCLIPXB.LIB (Blinker) in your application link script. By linking a .DLL statically, the .DLL will automatically be opened when the application is started and the symbols will be resolved at link time rather than at load time. This will insure that calls to functions in DCLIPX.DLL do not need to be used in macros, but that they can be used in your code like any other Xbase++ function.<br><br> NOTE: When using DCLIPX.DLL with your Xbase++ applications, you only need to distribute the DCLIPX.DLL and DCLIPS.DLL files with the application files. No other files are needed.<br><br>

Files:

DCLIPX.DLL

See Also:

   DCLIPX.LIB


DCLIP1.LIB

The dCLIP1 "Exports" library

DCLIP1.LIB is the library that contains a reference to the eXPress++ functions in DCLIP1.DLL that are "exported", ie callable from with Xbase++ applications.<br><br> This library must be listed in your link-script or project file when using eXPress++ functions in your application.<br><br>

Examples:

 -- Sample ALINK Link script --

 /*
 This link script creates XDEMO.EXE using .OBJ files compiled
 in COFF format and a DCLIPX.LIB file created in COFF format.
 Use this format when linking with ALINK.EXE.
 */

 /DE /OUT:XDEMO.EXE /PM:PM
 XMAIN.OBJ
 XDEMO.OBJ
 XDEMO1.OBJ
 XDEMO2.OBJ
 XDEMO3.OBJ
 XDEMO4.OBJ
 XDEMO5.OBJ
 XSAMPLE1.OBJ
 XSAMPLE2.OBJ
 EXPRESS.RES
 dclipx.lib

Files:

DCLIP1.LIB

See Also:

   DCLIP1.DLL


DCLIP2.LIB

The dCLIP2 "Exports" library

DCLIP2.LIB is the library that contains a reference to the eXPress++ functions in DCLIP2.DLL that are "exported", ie callable from with Xbase++ applications.<br><br> This library must be listed in your link-script or project file when using eXPress++ functions in your application.<br><br>

Examples:

 -- Sample ALINK Link script --

 /*
 This link script creates XDEMO.EXE using .OBJ files compiled
 in COFF format and a DCLIPX.LIB file created in COFF format.
 Use this format when linking with ALINK.EXE.
 */

 /DE /OUT:XDEMO.EXE /PM:PM
 XMAIN.OBJ
 XDEMO.OBJ
 XDEMO1.OBJ
 XDEMO2.OBJ
 XDEMO3.OBJ
 XDEMO4.OBJ
 XDEMO5.OBJ
 XSAMPLE1.OBJ
 XSAMPLE2.OBJ
 EXPRESS.RES
 dclipx.lib

Files:

DCLIP2.LIB

See Also:

   DCLIP2.DLL


DCLIPX.LIB

The dCLIPX "Exports" library

DCLIPX.LIB is the library that contains a reference to the eXPress++ functions in DCLIPX.DLL that are "exported", ie callable from with Xbase++ applications.<br><br> This library must be listed in your ALINK link-script when using eXPress++ functions in your application.<br><br>

Examples:

 -- Sample ALINK Link script --

 /*
 This link script creates XDEMO.EXE using .OBJ files compiled
 in COFF format and a DCLIPX.LIB file created in COFF format.
 Use this format when linking with ALINK.EXE.
 */

 /DE /OUT:XDEMO.EXE /PM:PM
 XMAIN.OBJ
 XDEMO.OBJ
 XDEMO1.OBJ
 XDEMO2.OBJ
 XDEMO3.OBJ
 XDEMO4.OBJ
 XDEMO5.OBJ
 XSAMPLE1.OBJ
 XSAMPLE2.OBJ
 EXPRESS.RES
 dclipx.lib

Files:

DCLIPX.LIB

See Also:

   DCLIPX.DLL


DCLIP1.DEF

The Source file for DCLIP1.DLL exported functions

DCLIP1.DEF is the source file that was used to create DCLIP1.LIB. the library containing "exported" symbols in DCLIP1.DLL.<br><br> This file is provided for reference only.<br><br>

Files:

DCLIP1.DEF

See Also:

   DCLIP1.LIB


DCLIP2.DEF

The Source file for DCLIP2.DLL exported functions

DCLIP2.DEF is the source file that was used to create DCLIP2.LIB. the library containing "exported" symbols in DCLIP2.DLL.<br><br> This file is provided for reference only.<br><br>

Files:

DCLIP2.DEF

See Also:

   DCLIP2.LIB


DCLIPX.DEF

The Source file for DCLIPX.DLL exported functions

DCLIPX.DEF is the source file that was used to create DCLIPX.LIB. the library containing "exported" symbols in DCLIPX.DLL.<br><br> This file is provided for reference only.<br><br>

Files:

DCLIPX.DEF

See Also:

   DCLIPX.LIB


EXPRESS.RES

Linking eXpress++ resources with your application

EXPRESS.RES is a file containing resources required by eXPress++ for proper operation. It includes mouse pointers, icons and bitmaps. It must be included in your link script to insure that the resources are properly linked to the application .EXE.<br><br>

Examples:

 -- Sample ALINK Link script --

 /DE /OUT:XDEMO.EXE /PM:PM
 XMAIN.OBJ
 XDEMO.OBJ
 XDEMO1.OBJ
 XDEMO2.OBJ
 XDEMO3.OBJ
 XDEMO4.OBJ
 XDEMO5.OBJ
 XSAMPLE1.OBJ
 XSAMPLE2.OBJ
 EXPRESS.RES
 dclipx.lib

Files:

EXPRESS.RES

See Also:

   EXPRESS.ARC


EXPRESS.ARC

The Source file for eXpress++ resources

EXPRESS.ARC is the source file that was used to create EXPRESS.RES, the file containing resources required by eXPress++ for proper operation. It includes mouse pointers, icons and bitmaps. <br><br> This file is provided for reference only.<br><br>

Files:

EXPRESS.ARC

See Also:

   EXPRESS.RES


DCCUSTOM.CH

The User-Defined, "custom" command set

The DCCUSTOM.CH file is an "include" file that is used to pre-process user-defined dot-prompt commands.<br><br> DCCUSTOM.CH is automatically loaded the first time a command is entered at the dot-prompt. This file must exist in your INCLUDE=<include> path or an error window will be displayed the first time you try to enter a command.<br><br> User-defined commands that are entered in this file will be available at the dot-prompt. <br><br> NOTE: It is recommended that you place all your user-defined commands in your own *.CH files and then #include these files in DCCUSTOM.CH. <br><br> CAUTION: If there are any syntax errors in the *.CH files you #include in DCCUSTOM.CH, an error window will be displayed the first time you try to enter a dot-prompt command.<br><br>

Files:

DCCUSTOM.CH

See Also:

   DCSTD.CH


DCPRINT.CH

The "Printer" Command set

The DCPRINT.CH file is an "include" file that is used to preprocess Clipper and Xbase++ @SAY.. style print commands to use the eXPress++ Printer class rather than the text-based system.<br><br> The printer class creates a printed page that is similar to the text-based printer page supported by SET DEVICE TO PRINT, except that it allows for any number of rows and columns on the page and provides a printer dialog setup system for the operator to choose the printer device, the default font, number of copies, etc.<br><br> The printer class allows for both text-based coordinates and pixel-based coordinates in the same print project. This allows for existing Clipper reports to be embellished with graphics, lines, font-changes, etc. without requiring the writing of an entirely new report. <br><br>

Examples:

#include "dcprint.ch"

PROCEDURE XTest( lPreview )

LOCAL aFor_Sale, oPrinter, i, nLineCount, cMemo, cMemoLine, cScrn

lPreview := IIF( Valtype(lPreview)='L',lPreview,.t.)

USE collect NEW

aFor_Sale := { 'No','Yes','Not Sure' }

BEGIN SEQUENCE

IF lPreview
  DCPRINT ON SIZE 60,100 TO oPrinter FONT '12.Courier' PREVIEW
ELSE
  DCPRINT ON SIZE 60,100 TO oPrinter FONT '12.Courier'
ENDIF

IF Valtype(oPrinter) # 'O' .OR. !oPrinter:lActive
  BREAK
ENDIF

DC_Gui(.t.)

IF !lPreview
  cScrn := DC_WaitOn()
ENDIF

DO WHILE !Eof()

  @ 2,0,20,45 DCPRINT BITMAP COLLECT->bitmap1
  @ 2,50,20,95 DCPRINT BITMAP COLLECT->bitmap2

  DCPRINT FONT '12.Courier'

  @ 23, 5, 37, 90 DCPRINT BOX

  @ 24,10 DCPRINT SAY '    Description:'
  @ 25,10 DCPRINT SAY '           Type:'
  @ 26,10 DCPRINT SAY '       Sub-Type:'
  @ 27,10 DCPRINT SAY '      Condition:'
  @ 28,10 DCPRINT SAY '       Location:'
  @ 29,10 DCPRINT SAY '      For Sale?:'
  @ 30,10 DCPRINT SAY '  Original Date:'
  @ 31,10 DCPRINT SAY '  Acquired Date:'
  @ 32,10 DCPRINT SAY ' Original Price:'
  @ 33,10 DCPRINT SAY 'Appraised Value:'
  @ 34,10 DCPRINT SAY '       Comments:'
  @ 35,10 DCPRINT SAY '      Bit Map 1:'
  @ 36,10 DCPRINT SAY '      Bit Map 2:'

  DCPRINT FONT '14.Terminal'

  @ 24,32 DCPRINT SAY COLLECT->descrip
  @ 25,32 DCPRINT SAY COLLECT->type
  @ 26,32 DCPRINT SAY COLLECT->sub_type
  @ 27,32 DCPRINT SAY COLLECT->condition
  @ 28,32 DCPRINT SAY COLLECT->location
  @ 29,32 DCPRINT SAY aFor_Sale[COLLECT->for_sale+1]
  @ 30,32 DCPRINT SAY COLLECT->date_orig
  @ 31,32 DCPRINT SAY COLLECT->date_acqu
  @ 32,32 DCPRINT SAY COLLECT->orig_price
  @ 33,32 DCPRINT SAY COLLECT->appr_value
  @ 34,32 DCPRINT SAY COLLECT->comments
  @ 35,32 DCPRINT SAY COLLECT->bitmap1
  @ 36,32 DCPRINT SAY COLLECT->bitmap2

  DCPRINT FONT '12.Arial'

  cMemo := Alltrim(COLLECT->memo)
  nLineCount := MLCount(cMemo)
  FOR i := 1 TO nLineCount - 1
    cMemoLine := MemoLine( cMemo, nil, i )
    IF Empty(cMemoLine)
      EXIT
    ENDIF
    @ 40+i,10 DCPRINT SAY cMemoLine
  NEXT

  DCPRINT EJECT

  SKIP

ENDDO

IF !lPreview
  DC_Impl(cScrn)
ENDIF

END SEQUENCE

DCPRINT OFF

RETURN

Files:

DCPRINT.CH

See Also:

   DCPRINT ON


DCDIALOG.CH

The "Robust Dialogue" command set

The DCDIALOG.CH file is an "include" file that is used to preprocess text-based and pixel-based dialog commands. Each command parses the properties of the dialog item into the Getlist array which is later passed to the eXPress++ GUI reader.<br><br> It is highly recommended that you use DCDIALOG.CH instead of EXPRESS.CH because it contains a much more robust set of commands that allows you to utilize the full power of the GUI dialogue system. These commands are "structurally" similar to the commands in EXPRESS.CH except @ .. SAY is changed to @ .. DCSAY and all other commands start with DC*. This was done so as to prevent conflicts with the standard Xbase++ command set and allow you to mix standard non-GUI @ SAY..GET commands and eXpress++ GUI @ DCSAY..GET commands in the same source code.<br><br> The eXPress GUI reader accepts a GetList array that contains the properties of Xbase Parts which can be combined into a complex dialogue system with very simple commands. This command system makes it easy to build dialogues using a simple procedural approach that is familiar to Clipper programmers rather than complicated object-oriented programming. You can combine @ SAY..GETs, ComboBoxes, ListBoxes, Multiline Gets, Icons, Bitmaps, Toolbars, CheckBoxes, RadioButtons, Pushbuttons, TabPages, 3-State objects, etc. all in a single Getlist to be passed to the GUI reader as a complete dialog.<br><br>

Examples:

/*
 This is an example of a dialogue with 3 tab pages.  The first
 tab page has a Get and a set of combo-boxes with picklist
 choices.  The second tabpage has a date field with a pop-up
 calendar and two numeric fields with pop-up calculator.
 The third tabpage has a multi-line get for editing a memo.
*/

#include 'dcdialog.ch'

PROCEDURE Xtest()

LOCAL oTabPage1, oTabPage2, oTabPage3, cDesc := Space(30),;
      aType := {'Star-Trek','Hollywood','Sports','Other'},;
      cType := Space(15), dDateOrig := Date(), dDateAcqu := Date(),;
      nOrigPrice := 0, nApprValue := 0, cMemo := '', ;
      GetList := {}

/* ---- Tab Page #1 ---- */

@  0,0 DCTABPAGE oTabPage1 CAPTION 'Collection' ;
   SIZE 72,15 PREOFFSET 0 POSTOFFSET 85

@  3,2  DCSAY "Description" GET cDesc SAYRIGHT PARENT oTabPage1

@  5,10  DCSAY "Type" PARENT oTabPage1 SAYSIZE 8

@  6,10 DCCOMBOBOX cType LIST aType SIZE 12,6 PARENT oTabPage1

/* ---- Tab Page #2 ---- */

@  0,0 DCTABPAGE oTabPage2 CAPTION 'Financial' ;
   RELATIVE oTabPage1

@  4,2 DCSAY "  Original Date" GET dDateOrig  PICT '99/99/9999' ;
   PARENT oTabPage2 SAYRIGHT

@  6,2 DCSAY "  Acquired Date" GET dDateAcqu  PICT '99/99/9999' ;
   PARENT oTabPage2 SAYRIGHT

@  8,2 DCSAY " Acquired Price" GET nOrigPrice PICT '9999.99'  ;
   PARENT oTabPage2 SAYRIGHT

@ 10,2 DCSAY "Appraised Value" GET nApprValue PICT '9999.99'  ;
   PARENT oTabPage2 SAYRIGHT

/* ---- Tab Page #3 ---- */

@  0,0 DCTABPAGE oTabPage3 CAPTION 'Memo' ;
   RELATIVE oTabPage2

@  5,2 DCMULTILINE cMemo PARENT oTabPage3 SIZE 65,8 ;
   FONT "10.Courier.Bold"

DCREAD GUI ;
   TITLE 'Tab-Page Demo' ;
   FIT ;
   ADDBUTTONS

RETURN

See Also:

   DIALOG GETLIST


DCDIR.CH

The "Directory Dialogue" command set

The DCDIR.CH file is an "include" file that is used to preprocess eXPress++ "directory" commands for use by the GUI reader system. Directory commands are commands which create directory and/or file choice dialogues via the eXPress++ GetList-style GUI reader. This include file contains commands like DCDIRTREE which is used to display a dialog that uses the XbpTreeView class to create a means for choosing a file from a directory tree.<br><br> The eXPress GUI reader accepts a GetList array that contains The properties of Xbase Parts can can be combined into a complex dialogue system with very simple commands. This command system makes it easy to build dialogues using a simple procedural approach that is familiar to Clipper programmers rather than complicated object-oriented programming. You can combine @ SAY..GETs, ComboBoxes, ListBoxes, Multiline Gets, Icons, Bitmaps, Toolbars, CheckBoxes, RadioButtons, Pushbuttons, TabPages, 3-State objects, etc. all in a single Getlist to be passed to the GUI reader as a complete dialog.<br><br>

Examples:

#include "dcdir.ch"

PROCEDURE XTest( )

LOCAL GetList := {}, oDirs, oFiles, cFileName, ;
      oFileName, cDirectory

cFileName := Space(30)
cDirectory := ''

@ 2,1 DCGET cFileName GETSIZE 40 GETOBJECT oFileName

@ 3.5,1 DCDIRTREE ;
       DIRS oDirs VAR cDirectory ;
       FILES oFiles VAR cFileName DATALINK {||oFileName:SetData()} ;
       SIZE 40,10.5 ;
       EXT '*.ICO','*.BMP','*.JPG','*.*'

DCREAD GUI ;
   TITLE 'eXPress++ Demo Program' ;
   FIT ;
   ADDBUTTONS

RETURN

See Also:

   DIALOG GETLIST


DCTREE.CH

The "Array-Tree Dialogue" command set

The DCTREE.CH file is an "include" file that is used to preprocess eXPress++ "array tree" commands for use by the GUI reader system. Array-Tree commands are commands which create array-browser dialogues via the eXPress++ GetList-style GUI reader. This include file contains commands like DCARRAYTREE which is used to display a dialog that uses the XbpTreeView class to create a means for browsing multiple dimensional arrays with various options.<br><br> The eXPress GUI reader accepts a GetList array that contains The properties of Xbase Parts can can be combined into a complex dialogue system with very simple commands. This command system makes it easy to build dialogues using a simple procedural approach that is familiar to Clipper programmers rather than complicated object-oriented programming. You can combine @ SAY..GETs, ComboBoxes, ListBoxes, Multiline Gets, Icons, Bitmaps, Toolbars, CheckBoxes, RadioButtons, Pushbuttons, TabPages, 3-State objects, etc. all in a single Getlist to be passed to the GUI reader as a complete dialog.<br><br>

Examples:

#include "dcdir.ch"

PROCEDURE XTest( )

LOCAL GetList := {}, oDirs, oFiles, cFileName, ;
      oFileName, cDirectory

cFileName := Space(30)
cDirectory := ''

@ 2,1 DCGET cFileName GETSIZE 40 GETOBJECT oFileName

@ 3.5,1 DCDIRTREE ;
       DIRS oDirs VAR cDirectory ;
       FILES oFiles VAR cFileName DATALINK {||oFileName:SetData()} ;
       SIZE 40,10.5 ;
       EXT '*.ICO','*.BMP','*.JPG','*.*'

DCREAD GUI ;
   TITLE 'eXPress++ Demo Program' ;
   FIT ;
   ADDBUTTONS

RETURN

See Also:

   DIALOG GETLIST


DCUDC.CH

The "User-Defined Command" template

The DCUDC.CH file is an "include" file that is used to preprocess eXPress++ "User Defined Commands" for use by the GUI reader system. Use this file as a "template" or an example for creating custom commands.<br><br> The eXPress GUI reader accepts a GetList array that contains The properties of Xbase Parts can can be combined into a complex dialogue system with very simple commands. This command system makes it easy to build dialogues using a simple procedural approach that is familiar to Clipper programmers rather than complicated object-oriented programming. You can combine @ SAY..GETs, ComboBoxes, ListBoxes, Multiline Gets, Icons, Bitmaps, Toolbars, CheckBoxes, RadioButtons, Pushbuttons, TabPages, 3-State objects, etc. all in a single Getlist to be passed to the GUI reader as a complete dialog.<br><br>

Examples:

#include "dcdir.ch"

PROCEDURE XTest( )

LOCAL GetList := {}, oDirs, oFiles, cFileName, ;
      oFileName, cDirectory

cFileName := Space(30)
cDirectory := ''

@ 2,1 DCGET cFileName GETSIZE 40 GETOBJECT oFileName

@ 3.5,1 DCDIRTREE ;
       DIRS oDirs VAR cDirectory ;
       FILES oFiles VAR cFileName DATALINK {||oFileName:SetData()} ;
       SIZE 40,10.5 ;
       EXT '*.ICO','*.BMP','*.JPG','*.*'

DCREAD GUI ;
   TITLE 'eXPress++ Demo Program' ;
   FIT ;
   ADDBUTTONS

RETURN

Files:

DCUDC.CH

See Also:

   USER-DEFINED COMMANDS
   DIALOG GETLIST


DCAPP.CH

The "Application Dialogue" command set

The DCAPP.CH file is an "include" file that is used to preprocess eXPress++ "application" commands for use by the GUI reader system. Application commands are commands which are compatible with Xbase++ "application parts" like APPEDIT, APPBROWSE and APPFIELD. The GetList version of these commands are DCAPPEDIT, DCAPPBROWSE and DCAPPFIELD, respectively, and are functionally equivalent.<br><br> The eXPress GUI reader accepts a GetList array that contains the properties of Xbase Parts which can be combined into a complex dialogue system with very simple commands. This command system makes it easy to build dialogues using a simple procedural approach that is familiar to Clipper programmers rather than complicated object-oriented programming. You can combine @ SAY..GETs, ComboBoxes, ListBoxes, Multiline Gets, Icons, Bitmaps, Toolbars, CheckBoxes, RadioButtons, Pushbuttons, TabPages, 3-State objects, etc. all in a single Getlist to be passed to the GUI reader as a complete dialog.<br><br>

Examples:

 #include "dcapp.ch"
 #include "xbp.ch"
 #include "gra.ch"
 #include "appevent.ch"

 PROCEDURE Xtest()

 LOCAL GetList := {}, GetOptions, oTabPage1, oTabPage2, oTabPage3, ;
       oStatic1, oStatic2, oStatic3, oToolBar, oAppEdit1, oAppEdit2, ;
       oAppEdit3

 USE COLLECT NEW SHARED

 /* ---- Tab Page #1 ---- */

 @  0,0 DCTABPAGE oTabPage1 CAPTION 'Plain' ;
    SIZE 80,20.5 PREOFFSET 0 POSTOFFSET 85 ;
    COLOR GRA_CLR_BLUE

 @  1.5,1 DCSTATIC XBPSTATIC_TYPE_RAISEDBOX SIZE 78,18.5 ;
    GROUP oStatic1 PARENT oTabPage1

 DCAPPEDIT INTO oAppEdit1 STYLE PLAIN POSITION 0,0 PARENT oStatic1

 /* ---- Tab Page #2 ---- */

 @  0,0 DCTABPAGE oTabPage2 CAPTION '3D' ;
    RELATIVE oTabPage1 ;
    COLOR GRA_CLR_RED

 @  1.5,1 DCSTATIC XBPSTATIC_TYPE_RAISEDBOX SIZE 78,18.5 ;
    GROUP oStatic2 PARENT oTabPage2

 DCAPPEDIT INTO oAppEdit2 STYLE 3D POSITION 0,0 PARENT oStatic2

 /* ---- Tab Page #3 ---- */

 @  0,0 DCTABPAGE oTabPage3 CAPTION 'Fancy' ;
    RELATIVE oTabPage2 ;
    COLOR GRA_CLR_YELLOW

 @  1.5,1 DCSTATIC XBPSTATIC_TYPE_RAISEDBOX SIZE 78,18.5 ;
    GROUP oStatic3 PARENT oTabPage3

 DCAPPEDIT INTO oAppEdit3 STYLE FANCY POSITION 0,0 PARENT oStatic3

 /* ---- Tool Bar ---- */

 DCTOOLBAR oToolBar ALIGN TOOLBAR_RIGHT SIZE 7.1

 DCADDBUTTON CAPTION '&Exit' ;
             PARENT oToolBar ;
             SIZE 7,1 ;
             ACTION {||DC_ReadGuiEvent(DCGUI_EXIT_OK)}

 DCGETOPTIONS WINDOW HEIGHT 440 ;
               WINDOW WIDTH 620

 DCREAD GUI ;
   OPTIONS GetOptions ;
   TITLE 'Application Edit Demo'

 CLOSE collect

 RETURN

See Also:

   DIALOG GETLIST


EXPRESS.CH

The "Clipper Compatabile" Command Set

The EXPRESS.CH file is an "include" file that is used to preprocess standard text-based Clipper and Xbase++ @SAY..GET commands and other screen-oriented, text-based command to use eXPress++ GUI and text-based readers rather than the standard Clipper-compatible reader.<br><br> It is highly recommended that once you get familiarized with the eXpress++ concept, that you use DCDIALOG.CH instead of EXPRESS.CH because it contains a much more robust set of commands that allows you to utilize the full power of the GUI dialogue system. These commands are "structurally" similar to the commands in EXPRESS.CH except @ .. SAY is changed to @ .. DCSAY and all other commands start with DC*. This was done so as to prevent conflicts with the standard Xbase++ command set and allow you to mix standard non-GUI @ SAY..GET commands and eXpress++ GUI @ DCSAY..GET commands in the same source code.<br><br> The eXPress GUI reader accepts a GetList array that contains the properties of Xbase Parts which can be combined into a complex dialogue system with very simple commands. This command system makes it easy to build dialogues using a simple procedural approach that is familiar to Clipper programmers rather than complicated object-oriented programming. You can combine @ SAY..GETs, ComboBoxes, ListBoxes, Multiline Gets, Icons, Bitmaps, Toolbars, CheckBoxes, RadioButtons, Pushbuttons, TabPages, 3-State objects, etc. all in a single Getlist to be passed to the GUI reader as a complete dialog.<br><br>

Files:

EXPRESS.CH


DCXTOC.CH

The Xbase to Clipper Interface definitions

The DCXTOC.CH file is an "include" file that contains definitions for the array that is passed to DC_XCCall(). This array is used to setup a call to the X2CLIP interface for calling a Clipper program to accomplished faster database operations.

Examples:

#include "dcxtoc.ch"

PROCEDURE XTest()

/*
This example demonstrates a re-indexing
progress bar which using the X2CLIP interface.
This interface spawns a Clipper
program to create the index.
*/

LOCAL aParams, nHandle, lStatus := .t., aIndex, oDlg, ;
      oSay, oProgress, bEval, lOk := .t., GetList := {}, ;
      i, nSeconds

nHandle := DC_XCOpen()
IF nHandle <= 0
  RETURN .f.
ENDIF

@ 1,1 DCSAY 'Creating Indexes'
@ 2,1 DCSAY '' SAYOBJECT oSay SAYSIZE 40
@ 4,1 DCPROGRESS oProgress SIZE 40,1.2 ;
      COLOR GRA_CLR_RED PERCENT ;
      EVERY IIF( nMode=1,100,1 )

DCREAD GUI EXIT FIT PARENT @oDlg ;
   TITLE "Indexing Example"

BEGIN SEQUENCE

aParams := DC_XCArray()
aParams[XC_ARRAY_DEFAULT] := 'C:\express\sample'
aParams[XC_ARRAY_DATABASE] := 'XTEST.DBF'
aParams[XC_ARRAY_RDD] := 'DBFCDX'
aParams[XC_ARRAY_OPERATION] := XC_OPENDATA
IF !DC_XCCall( nHandle, aParams )
  lOk := .f.
  BREAK
ENDIF

aIndex := { ;
   { 'AREACODE','AREACODE',nil,.f.,.f.}, ;
   { 'EXCHANGE','EXCHANGE',nil,.f.,.f.}, ;
   { 'CITY',    'CITY',nil,.f.,.f.}      ;
  }

bEval := {|nCurr,nMax|DC_GetProgress(oProgress,nCurr,nMax)}

nSeconds := Seconds()

FOR i := 1 TO Len(aIndex)
  oSay:setCaption('Creating Tag ' + aIndex[i,2])
  aParams := DC_XCArray()
  aParams[XC_ARRAY_DEFAULT] := 'C:\express\sample'
  aParams[XC_ARRAY_INDEX] := 'XTEST.CDX'
  aParams[XC_ARRAY_OPERATION] := XC_CREATEINDEX
  aParams[XC_ARRAY_TAG] := aIndex[i,1]
  aParams[XC_ARRAY_KEY] := aIndex[i,2]
  aParams[XC_ARRAY_FOR] := aIndex[i,3]
  aParams[XC_ARRAY_UNIQUE] := aIndex[i,4]
  aParams[XC_ARRAY_DESCEND] := aIndex[i,5]
  IF !DC_XCCall( nHandle, aParams, bEval, 5 )
    lOk := .f.
    BREAK
  ENDIF
NEXT

END SEQUENCE

oDlg:Destroy()

DC_XCClose( nHandle )

RETURN lOk

Files:

DCXTOC.CH

See Also:

   X2CLIP.EXE


DIALOG GETLIST

The Dialog Get-List Array

The eXPress++ dialogue system is based on a "Get-List" concept, similar to the one employed in Clipper and in Xbase++ text mode. The advantages of this concept are multifold:<br><br> 1. A dialog screen can be designed as a simple set of commands.<br><br> 2. The dialog can be saved to databases or arrays and used in data-driven applications.<br><br> 3. A dialog can be easily passed from one application to another or from one function to another in the same application.<br><br> 4. The dialog can be easily modified.<br><br> The Get-List is simply an array of dialog objects. eXPress++ commands are used to add objects to the Get-List. These commands are included in DCDIALOG.CH. Before using any DCDIALOG.CH commands you must first initialize the Getlist as an empty array like so: LOCAL GetList := {}<br><br> You may add as many commands as you wish to the Getlist and create complicated dialogue screens with multiple tabpages, static groups, browses, etc.<br><br> Use the function DC_READGETS(GetList) to invoke the Text or GUI reader. NOTE: some commands are only available in GUI mode so will be ignored the the text reader.<br><br> Each DC* command adds a sub-array of 61 elements to the main GetList array, with the exception of @ ..SAY..GET which adds two sub-arrays, one for the SAY and one for the GET. Each sub-array consists of the following items:<br><br> nGETLIST_TYPE<br><br> This is the type of object to paint on the dialogue screen. The supported types are defined in DCDIALOG.CH and are listed below:<br><br> GETLIST_DIALOG - DIALOG, XbpDialog() GETLIST_STATIC - STATIC, XbpStatic() GETLIST_GET - GET, XbpGet() GETLIST_MLE - MULTI-LINE GET, XbpMLE() GETLIST_3STATE - 3-STATE, Xbp3State() GETLIST_CHECKBOX - CHECKBOX, XbpCheckBox() GETLIST_COMBOBOX - COMBOBOX, XbpCombobox() GETLIST_LISTBOX - LIST BOX, XbpListBox() GETLIST_PUSHBUTTON - PUSHBUTTON, XbpPushButton() GETLIST_RADIOBUTTON - RADIO BUTTON, XbpRadioButton() GETLIST_SAY - SAY, XbpStatic() text GETLIST_ADDBUTTON - RADIO BUTTON, XbpStatic() on Toolbar GETLIST_SPINBUTTON - SPIN BUTTON, XbpSpinButton() GETLIST_GROUPBOX - GROUP BOX, XbpStatic() GETLIST_TABPAGE - TAB PAGE, XbpTabPage() GETLIST_SCROLLBAR - SCROLL BAR, XbpScrollBar() GETLIST_BITMAP - BIT MAP, XbpBitMap(), XbpPresSpace() GETLIST_METAFILE - METAFILE, XbpMetaFile() GETLIST_TOOLBAR - TOOLBAR, XbpStatic() GETLIST_MENUBAR - MENUBAR, XbpMenu() GETLIST_SUBMENU - SUB MENU, XbpMenu() GETLIST_MENUITEM - MENU ITEM, XbpMenu():additem GETLIST_BROWSE - BROWSE, XbpBrowse() GETLIST_BROWSECOL - BROWSE COLUMN, XbpColumn() GETLIST_MESSAGEBOX - MESSAGE AREA, XbpStatic() GETLIST_CUSTOM - CUSTOM OBJECT, Anything GETLIST_APPCRT - Application CRT Window - XbpCrt() GETLIST_APPEDIT - Application EDIT Window - APPEDIT GETLIST_APPBROWSE - Application BROWSE Window - APPBROWSE GETLIST_APPFIELD - Application FIELD - APPFIELD GETLIST_DIRTREE - Directory Tree DIALOG - XbpTreeView() GETLIST_STATUS - Status Bar GETLIST_PROGRESS - Progress Bar, XbpStatic() GETLIST_HOTKEY - Hot Key accelerator GETLIST_PICKLIST - Special Pick-List Dialog GETLIST_USER - User-Defined Commands (Start Offset) GETLIST_DATASTORE - Reserved for storage of Static Data<br><br> nGETLIST_SUBTYPE<br><br> This is used only on objects that have a sub-type such as DCSTATIC objects. Sub-Types are usually defined in XBP.CH.<br><br> cGETLIST_CAPTION<br><br> This is used on objects that have a caption like DCSTATIC, DCPUSHBUTTON, etc.<br><br> bGETLIST_VAR<br><br> This is an "anchor" code block which is usually used as the :datalink to the Xbase part. The function DC_GetAnchorCB() is used to create a code block which provides access to a local memory variable. For example, if this object were a GET, the code block may look like this:<br><br> {|x| IIf( PCount()==0 , uVar, uVar:=x) }<br><br> It is also be used to provide a link to a local array which is used for list-boxes, combo-boxes, etc.<br><br> It can be passed as a single code block or as an array of two elements: the first being the code block and the second being the string representation of the code block. Passing an array allows for "data-driven" applications because the reader will automatically macro-compile the string to a code-block if the code block does not exist. <br><br> nGETLIST_STARTROW<br><br> This is the Start Row of the object, relative to 0 (top) of the parent object, unless bGETLIST_RELATIVE contains a code-block. If lGETLIST_PIXEL is .TRUE. then this should be in pixels, otherwise it is in text-based coordinates.<br><br> nGETLIST_STARTCOL<br><br> This is the Start Column of the object, relative to 0 (left) of the parent object, unless bGETLIST_RELATIVE contains a code-block. If lGETLIST_PIXEL is .TRUE. then this should be in pixels, otherwise it is in text-based coordinates.<br><br> nGETLIST_ENDROW<br><br> This is the End Row of the object, relative to 0 (top) of the parent object. If lGETLIST_PIXEL is .TRUE. then this should be in pixels, otherwise it is in text-based coordinates.<br><br> nGETLIST_ENDCOL<br><br> This is the End Column of the object, relative to 0 (left) of the parent object. If lGETLIST_PIXEL is .TRUE. then this should be in pixels, otherwise it is in text-based coordinates.<br><br> nGETLIST_WIDTH<br><br> This is the Width of the object. If lGETLIST_PIXEL is .TRUE. then this should be in pixels, otherwise it is a text-based number.<br><br> nGETLIST_HEIGHT<br><br> This is the Height of the object. If lGETLIST_PIXEL is .TRUE. then this should be in pixels, otherwise it is a text-based number.<br><br> oGETLIST_FONT<br><br> The is the Font. If left empty, then the font is inherited from the parent. This may be a font object created by XbpFont() or the name of a font.<br><br> cGETLIST_PICTURE<br><br> This is a picture clause and is used only with GET objects to define the picture of the GET, ex: "99/99/9999".<br><br> bGETLIST_WHEN<br><br> This is a code block which is evaluated after other events which may affect memory variables or database pointers in the application. If the return value of the code block is .FALSE. then the object is disabled with the :disable() method. If the return value of the code block is .TRUE. then the object is enabled with the :enable() method.<br><br> It can be passed as a single code block or as an array of two elements: the first being the code block and the second being the string representation of the code block. Passing an array allows for "data-driven" applications because the reader will automatically macro-compile the string to a code-block if the code block does not exist.<br><br> bGETLIST_VALID<br><br> This is a code block which is evaluated when the object loses focus. If the return value is .FALSE. then the object remains in focus.<br><br> It can be passed as a single code block or as an array of two elements: the first being the code block and the second being the string representation of the code block. Passing an array allows for "data-driven" applications because the reader will automatically macro-compile the string to a code-block if the code block does not exist.<br><br> cGETLIST_TOOLTIP<br><br> This is a message to display in a "tool-tip" when the mouse is placed over the object.<br><br> xGETLIST_CARGO<br><br> This is any kind of data you wish to to add to the :cargo container for this object. The cargo may be accessed at any time via the <oObject>:cargo exported variable, however it will not be stored in the same manner it is entered. The :cargo container of DCDIALOG objects is an array of at least three elements:<br><br> [1] - A numeric value that is a pointer to the Getlist array for this object.<br><br> [2] - A pointer to the GetList array.<br><br> [3] - The value of <xCargo>.<br><br> [4] and up - optional values added by the GUI reader.<br><br> aGETLIST_PRESENTATION<br><br> This is an array of presentation parameters that conforms to the standard presentation specification for Xbase parts.<br><br> This is a two dimensional array. If specified, this contains presentation parameters for the Xbase Parts object. The first column of the array must contain #define constants from the XBP.CH file starting with the prefix XBP_PP_. These constants define the presentation parameters that can be set for the Xbase Parts object and include colors and fonts. The second column of the array contains the value for each setting. These are usually set using #define constantse from the GRA.CH file:<br><br> bGETLIST_ACTION<br><br> This is a code block that is evaluated by some Xbase Parts objects which cause an action, such as a Push-Button or a menu item.<br><br> It can be passed as a single code block or as an array of two elements: the first being the code block and the second being the string representation of the code block. Passing an array allows for "data-driven" applications because the reader will automatically macro-compile the string to a code-block if the code block does not exist. oGETLIST_OBJECT<br><br> This is a spare. This is an "anchor" code block which is used to assign a local variable to the Xbase Part after it is created by DC_ReadGui().<br><br> xGETLIST_ORIGVALUE<br><br> This is an empty container which is used by DC_ReadGui() to store the original value of the variable which has been data- linked to the Xbase Parts object.<br><br> xGETLIST_OPTIONS<br><br> This is used to pass optional parameters to the Xbase Part. Some objects have additional features, such as the :spinFast option of a SPIN BUTTON. Features that are unique to an object are handled here.<br><br> aGETLIST_COLOR<br><br> This is a two-element array consisting of a ForeGround and a BackGround color for the object. By default, the object inherits the colors of the parent object. The values in the array my be color-strings that conform to SetColor() type colors or numerical values that conform to GRA_* type colors defined in GRA.CH.<br><br> The colors may also be set via aGETLIST_PRESENTATION.<br><br> cGETLIST_MESSAGE<br><br> This is the text of a message which is display in a DCMESSAGEBOX object when this object has focus.<br><br> cGETLIST_HELPCODE<br><br> This is the help code that is passed to DC_HelpF1() "in text mode" or to a *.HLP file "in GUI mode" if the F1 (Help) key is pressed when this object is in focus. In GUI mode, the GET option HELPFILE <cHelpFile> is required to identify the Windows .HLP file containing the context help.<br><br> cGETLIST_VARNAME<br><br> This is the character string name of the variable that has been data-linked to the object via bGETLIST_VAR<br><br> bGETLIST_READVAR<br><br> This is provided for compatability with DC_ReadModal(), text- based gets.<br><br> It can be passed as a single code block or as an array of two elements: the first being the code block and the second being the string representation of the code block. Passing an array allows for "data-driven" applications because the reader will automatically macro-compile the string to a code-block if the code block does not exist.<br><br> bGETLIST_DELIMVAR<br><br> This is an "anchor" code block which is used to assign a local variable to the delimeter variable. A delimeter variable is only used by text-based Radio-Buttons and Check-boxes and is needed with DC_ReadModal(), the Text-based reader.<br><br> It can be passed as a single code block or as an array of two elements: the first being the code block and the second being the string representation of the code block. Passing an array allows for "data-driven" applications because the reader will automatically macro-compile the string to a code-block if the code block does not exist. <br><br> bGETLIST_GROUP<br><br> This is an "anchor" code block which is used to assign a local variable to the Xbase Part after it is created by DC_ReadGui(). The local variable is used as a pointer to this object when it it needed as a "parent" to other objects.<br><br> It can be passed as a single code block or as an array of two elements: the first being the code block and the second being the string representation of the code block. Passing an array allows for "data-driven" applications because the reader will automatically macro-compile the string to a code-block if the code block does not exist.<br><br> nGETLIST_POINTER<br><br> This is a numeric pointer to another GetList item which may be associated with this item. The number is a GetList sub-array. For example, a GETLIST_GET item is associated with a GETLIST_SAY item.<br><br> bGETLIST_PARENT<br><br> This is an "anchor" code block which is used to assign a local variable to the Xbase Part after it is created by DC_ReadGui(). The local variable is used as a pointer to the "parent" object which this object attaches itself to.<br><br> It can be passed as a single code block or as an array of two elements: the first being the code block and the second being the string representation of the code block. Passing an array allows for "data-driven" applications because the reader will automatically macro-compile the string to a code-block if the code block does not exist. bGETLIST_REFVAR<br><br> This is an "anchor" code block which is usually used as the :datalink to the Xbase part. The function DC_GetAnchorCB() is used to create a code block which provides access to a local memory variable. This is used only when bGETLIST_VAR is used for another purpose such as a pointer to an array for a LIST BOX.<br><br> It can be passed as a single code block or as an array of two elements: the first being the code block and the second being the string representation of the code block. Passing an array allows for "data-driven" applications because the reader will automatically macro-compile the string to a code-block if the code block does not exist. lGETLIST_PROTECT<br><br> This is used on objects that get and display information. If this is .TRUE. then the data is protected from editing.<br><br> lGETLIST_PIXEL<br><br> This is used to establish whether coordinate and size parameters are in PIXELS or text-based. If this is .FALSE., then the coordinate and size parameters are converted to pixel-based by the GUI reader.<br><br> nGETLIST_CURSOR<br><br> This is the resource id of an alternate mouse cursor to use for this object.<br><br> bGETLIST_EVAL<br><br> This code-block is evaluated as the "last step" after an object is created by the GUI reader. The object is passed to the code block. It may be used for anything that may be required during the intialization process of an object by the GUI reader. For example, let's say we have a static object that displays a color using GraBox(). We want to insure that the object is refilled with the color whenever it is repainted. We accomplish this with the following codeblock:<br><br> {|o|o:paint := {|o|RGB(o,nRed,nGreen,nBlue)} }<br><br> It can be passed as a single code block or as an array of two elements: the first being the code block and the second being the string representation of the code block. Passing an array allows for "data-driven" applications because the reader will automatically macro-compile the string to a code-block if the code block does not exist.<br><br> bGETLIST_RELATIVE<br><br> This is an "anchor" code block which is used to assign a local variable to the Xbase Part after it is created by DC_ReadGui(). The local variable is used as a pointer to a "relative" object which contains the master coordinates. If this codeblock evaluates to an object type, then the object's current position coordinates are used to locate this object and the start column / start row are relative to the start coordinates of the object.<br><br> RELATIVE addressing is recommended because dialog screen objects usually have a positional relationship to each other on the screen and designing screens is much faster when a master object is moved and all other objects move in relationship to the master.<br><br> It can be passed as a single code block or as an array of two elements: the first being the code block and the second being the string representation of the code block. Passing an array allows for "data-driven" applications because the reader will automatically macro-compile the string to a code-block if the code block does not exist. aGETLIST_OPTIONS2 - aGETLIST_OPTIONS9<br><br> These elements are provided for special use.<br><br> aGETLIST_LEVEL<br><br> This is an optional character string used for "sorting" the Getlist and to establish a heirarchy tree for GetList items. It is used by the dCLIP++ DC_DlgEdit() DIALOG editor to associate parent items with child items. <br><br> aGETLIST_TITLE<br><br> This is an optional character string used as a "title" for the Getlist object. It is used by the dCLIP++ DC_DlgEdit() DIALOG editor when displaying a Tree-style browse of the Get List.<br><br> cGETLIST_ACCESS<br><br> This is an optional "lock code" to apply to the Getlist item. It is used by dCLIP++ to provide lock and key access to individual items in the Getlist dependent on user access rights.<br><br> bGETLIST_COMPILE<br><br> This is an optional code block which is evaluated at the time the GetList is loaded by the reader. If the code block returns a .TRUE., then this item is added to the dialog window, If the code block returns a .FALSE. then this item is ignored. Use this option when it is necessary to have "conditional compiling" capability in applications.<br><br> cGETLIST_ID<br><br> This is a unique ID for the GetList item. It is reserved for use by dCLIP++.<br><br> dGETLIST_REVDATE<br><br> This is the last revised date for this object in the Getlist. It is used by the dCLIP++ DIALOG editor.<br><br> cGETLIST_REVTIME<br><br> This is the last revised time for this object in the Getlist. It is used by the dCLIP++ DIALOG editor.<br><br> cGETLIST_REVUSER<br><br> This is the USER ID of the user or programmer who last revised this Getlist item via the dCLIP++ DIALOG editor.<br><br> bGETLIST_HIDE<br><br> This is a code block which is evaluated after other events which may affect memory variables or database pointers in the application. If the return value of the code block is .FALSE. then the object is hidden with the :hide() method. If the return value of the code block is .TRUE. then the object is displayed with the :show() method.<br><br> It can be passed as a single code block or as an array of two elements: the first being the code block and the second being the string representation of the code block. Passing an array allows for "data-driven" applications because the reader will automatically macro-compile the string to a code-block if the code block does not exist.<br><br> nGETLIST_ACCELKEY<br><br> This is a numeric value equal to xbeK_* numbers that define keyboard keys in appevent.ch. Pressing the associated key will either perform the action associated with the object for objects like PushButtons, Check-Boxes, Radio-Buttons, Menu Items, etc. or will set input focus to the associated object if the object is not an action object.<br><br> bGETLIST_GOTFOCUS <br><br> This optional code block is evaluated when this object receives input focus.<br><br> bGETLIST_LOSTFOCUS<br><br> This optional code block is evaluated when this object loses input focus. lGETLIST_TABSTOP, <br><br> This logical value when .TRUE. will cause the object (Xbase Part) to be set when using the Tab key. Note: When logical groups are defined in a dialog using TABGROUP <nTabGroup>, TABSTOP is usually set to .T. (true) for the first dialog element in the group. This allows the first dialog element of a group to be activated using the Tab key. <br><br> nGETLIST_TABGROUP<br><br> This option numeric value allows objects (Xbase Parts) that are created immediately after one another in the GetList to be combined into logical groups. This allows the user to navigate within a dialog from group to group by pressing the Tab key. Within a group of dialog elements navigation is performed using the cursor keys. <br><br> Only constants defined in the XBP.CH file can be used as values for this instance variable. The following table lists the available constants: <br><br> #define constants for <nTabGroup>:<br><br> Constant Description <br><br> XBP_NO_GROUP *) Dialog element does not belong to a group XBP_BEGIN_GROUP Dialog element is the first in a group (this begins the definition of the group) XBP_WITHIN_GROUP Dialog element is within a group XBP_END_GROUP Dialog element is the last in a group (this ends the definition of the group) <br><br> *) Default value<br><br> lGETLIST_VISIBLE<br><br> This option determines whether the object is visible immediately after the call to the method :create() . By default the object follows the VISIBLE clause of the DCGETOPTIONS command. Use the INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS<br><br> cGETLIST_GETGROUP<br><br> This option is a "group" name (case-sensitive) to assign to this GetList object. Assignment to a group makes it possible to perform operations only on GetList items which are members of a specified group, using functions such as DC_GetRefresh() or DC_ReadGui().<br><br> lGETLIST_FLAG<br><br> This logical element is reserved for the form designer.<br><br>

See Also:

   dc_readgets()
   dc_readgui()
   DIALOG OPTIONS


DIALOG OPTIONS

The Dialog Get Options Array

The Dialog Options List is simply a single-dimensionsal array of 24 elements. eXPress++ Dialog options are included in DCDIALOG.CH. Before using the DCGETOPTIONS command you must first initialize the GetOptions array variable so: LOCAL GetOptions <br><br> The elements of the options array are defined as follows:<br><br> cGETOPT_NAME<br><br> This is the name of the Dialog screen or application. It must be all Upper Case characters no longer than characters in length. It is a unique name assigned to the dialog for saving to the dCLIP++ DIALOG dictionary database.<br><br> cGETOPT_TITLE<br><br> This is the title or description of the dialog.<br><br> nGETOPT_WNDHEIGHT <br><br> This is the dialog window height in pixels.<br><br> nGETOPT_WNDWIDTH <br><br> This is the dialog window width in pixels.<br><br> nGETOPT_ROWSPACE <br><br> This is the number of pixels between rows when using text- based coordinates in the Getlist. The default is 20.<br><br> nGETOPT_SAYWIDTH <br><br> This is the default width for DCSAY objects if the SAYSIZE parameter is not used with the DCSAY command.<br><br> cGETOPT_SAYFONT <br><br> This is the default FONT for DCSAY objects if the FONT parameter is not used with the DCSAY command. If this parameter is NIL, then the DCSAY object uses the font of the parent. cGETOPT_GETFONT <br><br> This is the default FONT for DCGET and @..DCSAY..GET objects if the FONT parameter is not used with the DCGET or @..DCSAY..GET commands. If this parameter is NIL, then the object uses the font of the parent.<br><br> nGETOPT_GETHEIGHT <br><br> This is the default HEIGHT (in pixels) of the GET in DCGET and @..DCSAY..GET commands. If this parameter is nil, then the default height is 20.<br><br> aGETOPT_BUTTONS // to be implemented in Rev 1.1 <br><br> This is an optional multi-dimensional array of buttons to add to the bottom of the dialog box. Each button will be added in sequence from left to right. Each sub-array is an array of 5 elements defining the buttons.<br><br> Element Type Description ------- ---- ------------------------------------ 1 C Button Caption 2 N Button Width (in pixels) 3 N Button Height (in pixels) 4 B Action Code Block 5 X Button Cargo<br><br> nGETOPT_WNDROW <br><br> This is the starting row of the dialog window (in pixels). If this element is NIL, then the dialog will be centered vertically in the parent. nGETOPT_WNDCOL <br><br> This is the starting column of the dialog window (in pixels). If this element is NIL, then the dialog will be centered horizontally in the parent. nGETOPT_ROWOFFSET <br><br> This is the row offset (in pixels) to add to each dialog object. The default is 0.<br><br> nGETOPT_COLOFFSET <br><br> This is the column offset (in pixels) to add to each dialog object. The default is 0.<br><br> lGETOPT_DESIGN <br><br> If this element is .TRUE., then the user can move and resize objects on the screen. Objects that are moved and resized are saved back in the GetList array.<br><br> aGETOPT_MENU <br><br> This is a multi-dimensional array containing an optional menu to attach to the top of the dialog window. The menu must conform to the specifications of menus returned by the dCLIP menu dictionary system. See DC_MenuLoad().<br><br> lGETOPT_PIXEL <br><br> If this element is .TRUE., then all coordinates in the Getlist are in pixels, otherwise they are text-based coordinates.<br><br> xGETOPT_SPARE<br><br> Spare.<br><br> nGETOPT_ICON <br><br> This is the resource ID of the ICON to place in the upper left corner of the dialog window. <br><br> lGETOPT_CHECKGET <br><br> If this element is .TRUE., then all DCGET or @..DCSAY..GET objects which GET a logical value will be displayed as a CheckBox rather than a normal GET.<br><br> cGETOPT_HELPFILE <br><br> This is the name of a *.HLP help file to activate when the user clicks on the HELP button on the bottom of the dialog window.<br><br> lGETOPT_VISIBLE <br><br> If this element is .TRUE., then the dialog window will be displayed before objects are created on the window, otherwise the entire dialog will not be displayed until all objects are created.<br><br> lGETOPT_TRANSLATE<br><br> If this element is .TRUE., then it is assumed that all coordinates in the GetList are based on 0,0 being the upper left home position of the display or parent object. It is also assumed that coordinates are text-based unless individually specified as pixel-based by the aGETLIST_PIXEL. A .TRUE. will also insure that RELATIVE coordinates are based on the coordinates of the relative objects specified in the Getlist. If this element is .FALSE., then NO TRANLATIONS will occur when the objects are displayed by the GUI reader and all coordinates are assumed to be based on 0,0 being the lower left home position of the display or parent object and are all pixel-based. After the GUI reader translates the coordinates, it writes the translated coordinates back to the Getlist and automatically sets this flag to .FALSE. so that successive calls to the GUI reader with the translated Getlist will not cause anomolies when displaying the objects.<br><br> lGETOPT_SAYRIGHT<br><br> If this element is .TRUE. then all GETLIST_SAY type objects in the Getlist will display their text right-justified, unless that object specificies LEFT or CENTER justification via the aGETLIST_OPTIONS element of the Getlist item.<br><br> nGETOPT_BITMAP<br><br> This is the resource ID of a Bitmap that is linked into the .EXE. This bitmap will be sized to fill the main dialog window.<br><br> aGETOPT_PRESENT<br><br> The PRESENTATION option is a two-dimensional array that contains presentation parameters for the Dialog window. The first column of the array must contain #define constants from the XBP.CH file starting with the prefix XBP_PP_. These constants define the presentation parameters that can be set for the object and include colors and fonts. The second column of the array contains the value for each setting. These are also generally set using #define constants from the GRA.CH file.<br><br> nGETOPT_BGCOLOR <br><br> This option is a numeric value defining the background color of the dialog windows. Colors start with GRA_CLR_* (defined in GRA.CH.<br><br> nGETOPT_SAYOPT <br><br> Objects created by the @DCSAY command can be given a set of options which are used to align the text within the rectangular area of the say (XbpStatic) object. Constants defined in the XBP.CH file are used for these options. These constants are listed in the table below. If combinations of alignment options are required, the sum of the appropriate constants must are assigned to the instance variable :options . <br><br> #define constants for aligning text <br><br> Constant Description <br><br> XBPSTATIC_TEXT_LEFT Text is left aligned XBPSTATIC_TEXT_CENTER Text is horizontally centered XBPSTATIC_TEXT_RIGHT Text is right aligned XBPSTATIC_TEXT_TOP Text is displayed at top XBPSTATIC_TEXT_VCENTER Text is vertically centered XBPSTATIC_TEXT_BOTTOM Text is displayed at bottom <br><br> bGETOPT_EVAL <br><br> This option is a code block that is evaluated after the main dialog window (XbpDialog) is created. This code block is evaluated before any items from the GetList are created and added to the Dialog. The Dialog object is passed to the code block. <br><br> nGETOPT_MODALSTATE <br><br> This element is used to set the Modal State of the dialog window. Options are XBP_DISP_APPMODAL or XBP_DISP_MODELESS (defined in XBP.CH).<br><br> nGETOPT_SAYHEIGHT <br><br> This option is the default HEIGHT (in pixels) of the SAY in @..DCSAY and @..DCSAY..GET commands. If this element is empty then the default height is 20. <br><br> lGETOPT_MINBUTTON <br><br> A logical .TRUE. in this element will suppress the display of the Minimize button on the dialog window. <br><br> lGETOPT_MAXBUTTON <br><br> A Logical .TRUE. in this element will suppress the display of the Maximize button on the dialog window.<br><br> lGETOPT_TABSTOP <br><br> A Logical .TRUE. in this element will cause all objects (Xbase Parts) to be set when using the Tab key. The default for TabStop is .False. or OFF. The TabStop setting for individual objects can be force to ON or OFF by using the TABSTOP or NOTABSTOP commands respectively in each command to override the default setting. <br><br> lGETOPT_ABORTQUERY <br><br> A Logical .TRUE. in this element will cause a Message Box to appear Confirming that the cancelling of operation when the Cancel button is clicked or the Dialog window is closed. <br><br> nGETOPT_ROWPIXELS <br><br> A numerical value in this element is the amount of pixels that equate to a row when using text-based coordinates. The default is 20. <br><br> nGETOPT_COLPIXELS <br><br> A numerical value in this element is the amount of pixels that equate to a column when using text-based coordinates. The default is 7.0.<br><br> lGETOPT_ESCAPEKEY <br><br> A Logical .FALSE. in this element will disable the ESCape key. Normally, the ESCape key will close the dialog window and cancel operation. <br><br> cGETOPT_SOURCECODE // feature available in Rev. 1.1 <br><br> This element contains the name of the source code (*.PRG) file that contains the DC* commands which created the dialog GetList. This is needed when using the pop-up Dialog Editor in DESIGN mode. Changes made to a dialog are re-written to the source code file only if the command is identified by an ID, GETID or SAYID clause.<br><br> aGETOPT_TOOLCOLOR <br><br> This element contains an optional 2-element array defining the he foreground color and background color of tooltips when using the TOOLTIP clause on eXPress++ commands. The default colors are GRA_CLR_BLACK and GRA_CLR_WHITE.<br><br> nGETOPT_BORDER<br><br> This element defines the border type of the dialog window. Constants defined in the XBP.CH file can be assigned to <nBorder>. The following table shows the valid #define constants. Constant Description <br><br> XBPDLG_NO_BORDER No border XBPDLG_SIZEBORDER Window is sizeable XBPDLG_THINBORDER *) Thin border, window size cannot be changed XBPDLG_DLGBORDER Thick border, window size cannot be changed XBPDLG_RAISEDBORDERTHICK **) Thick, raised border <br><br> XBPDLG_RAISEDBORDERTHIN *) Thin, raised border XBPDLG_RECESSEDBORDERTHICK Thick, recessed border XBPDLG_RECESSEDBORDERTHIN *) Thin, recessed border XBPDLG_RAISEDBORDERTHICK_FIXED Thick, raised border, size cannot be changed XBPDLG_RAISEDBORDERTHIN_FIXED *) Thin, raised border, size cannot be changed <br><br> XBPDLG_RECESSEDBORDERTHICK_FIXED Thick, recessed border, size cannot be changed XBPDLG_RECESSEDBORDERTHIN_FIXED *) Thin, recessed border, size cannot be changed <br><br> *) not supported by Windows **) Default border<br><br> If a dialog is embedded as MDI client within another dialog, Windows ignores all border styles except XBPDLG_RAISEDBORDERTHICK and XBPDLG_RECESSDBORDERTHICK. In all other cases, a border is displayed for MDI clients that corresponds to XBPDLG_RAISEDBORDERTHICK. <br><br> lGETOPT_EXVALID<br><br> This element if .TRUE. will traverse the GetList when the user clicks on the OK button and test all validations. If any validation fails, the failed object will receive input focus and the dialog will remain active.<br><br> lGETOPT_NOTASKLIST<br><br> This element if .TRUE. will insure that the dialog window is not placed on the Windows task bar.<br><br> nGETOPT_MINSIZE<br><br> This element is used to establish the minimum size of the dialog window, in pixels, if the operator attempts to resize the window.<br><br> nGETOPT_MAXSIZE<br><br> This element is used to establish the maximum size of the dialog window, in pixels, if the operator attempts to resize the window.<br><br> lGETOPT_NORESIZE<br><br> This element if .TRUE. will prevent the operator from resizing the dialog window.<br><br> lGETOPT_NOTITLEBAR<br><br> This element if .TRUE. will prevent a titlebar from displaying on the dialog window. This will also prevent the minimize, maximize, and close buttons from appearing.<br><br> lGETOPT_NOMOVE<br><br> This element if .TRUE. will prevent the dialog window from automatically moving when it's owner is moved.<br><br> nGETOPT_ORIGIN<br><br> This element defines the reference point for the position of the dialog window. The value of <nOrigin> must be a #define constant from the file XBP.CH. The available constants are listed in the following table: <br><br> Constants for the origin of a dialog window <br><br> Constant Description <br><br> XBPDLG_ORIGIN_OWNER *) Origin is point {0,0} of the owner window XBPDLG_ORIGIN_SCREEN Origin is point {0,0} of the desktop window XBPDLG_ORIGIN_MOUSE Origin is the current mouse position <br><br> *) Default value <br><br> nGETOPT_HILITEGETS<br><br> This element defines the color of a box that will be drawn around the currently selected GET. The numeric value must be a GRA_CLR_* color defined in GRA.CH. This clause highlights only the GET portion of @.DCSAY..GET commands and DCGET commands. The feature is disabled if this element is a NIL.<br><br> lGETOPT_SUPERVISE<br><br> This element if .FALSE. will cause the ENTER key to move from the last get of a group of gets to the first get of the next group of gets. Default behavior (.TRUE.) is for the movement from the last get to the first get of a group of gets that all have the same parent.<br><br> For example, if there are gets on 3 different tab pages, and the user is in the last get of TabPage 1, and ENTER will cause the first get on TabPage 2 to acquire focus.<br><br><br><br><br><br><br><br><br><br>

See Also:

   DIALOG GETLIST


OVERVIEW_DUAL_COMM

Dual-Mode Commands

DUAL-Mode commands have been designed to work in either TEXT mode or GUI mode. Text mode is selected by calling DC_GUI(.f.) and GUI mode is selected by calling DC_GUI(.t.).<br><br> 


OVERVIEW_GUI_COMM

GUI commands

GUI commands are designed to work only in GUI mode. When any of these commands are used, the dialog reader should be invoked with the DCREAD GUI command or the DC_ReadGUI() function.<br><br> 


@ DC3STATE

Create a 3-STATE object for displaying with the GUI reader

The command @..DC3STATE creates a new 3-State definitiion and adds it to the array named GETLIST which is later processed by the DC_Read*() functions or by the DCREAD * command. The GETLIST array must be first declared and initialized to the value of {}.<br><br> The command DCREAD GUI creates the DC_Xbp*() objects and activates the edit mode for all definitions found in the GetList array. <br><br> The command DCREAD HTML creates the DC_Html*() objects and writes the HTML source code.<br><br> A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released.<br><br> @..DC3STATE objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCRADIO, @..DCPUSHBUTTON or @..DCTABPAGE.<br><br>

Syntax:

@ <nRow>,<nCol> DC3STATE <uVar> ;
                [PROMPT <aVar>] ;
                [SIZE <nWidth> [,<nHeight>]] ;
                [PARENT <oParent>] ;
                [PARENTID <cParentID>] ;
                [MESSAGE <bcMsg> [INTO <oMsg>]] ;
                [COLOR <bncFgC> [,<ncBgC>] ] ;
                [HELPCODE <cHelp>] ;
                [DATALINK <bLink>] ;
                [FONT <bocFont>] ;
                [WHEN <bWhen>] ;
                [PRESENTATION <aPres>] ;
                [PIXEL] ;
                [OBJECT <oObject>] ;
                [TOOLTIP <bcToolTip>] ;
                [CURSOR <nCursor>] ;
                [CARGO <xCargo>] ;
                [HIDE <bHide>] ;
                [EDITPROTECT <bProtect>] ;
                [PREEVAL <bPreEval>] ;
                [EVAL <bEval>] ;
                [TITLE <cTitle>] ;
                [RELATIVE <oRel>] ;
                [ID <cId>] ;
                [ACCELKEY <anAccel>] ;
                [GOTFOCUS <bGotFocus>] ;
                [LOSTFOCUS <bLostFocus>] ;
                [TABSTOP] ;
                [NOTABSTOP] ;
                [TABGROUP <nTabGroup>] ;
                [VISIBLE] ;
                [INVISIBLE] ;
                [GROUP <cGroup>] ;
                [VALID <bValid>] ;
                [RESIZE <aResize> [SCALEFONT] ] ;
                [DRAG <bDrag> [DIALOG <bDD>] ;
                [DROP <bDrop> [CURSOR <nDropCursor>] ;
                [SUBCLASS <cSubClass>]

Arguments:

<nRow> and <nCol> are the row and column of the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE <oRel> argument is
used.  If no parent is assigned, then the parent is the Dialog
box. IF the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel
mode by including PIXEL as a command argument.

<nVar> is the variable to GET.  This must be a initialized to
a numerical value of 0, 1 or 2. It must not be a macro. <nVar>
is automatically anchored via a Get-Set codeblock created by
DC_GetAnchorCB() unless <nVar> is a custom Get-Set code block.
Macros may be used in a custom Get-Set code block.

OBJECT <oObject> is the variable to use as a container for the
object after it is created by the GUI reader.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

PROMPT <aPrompt> is an array of 3 character strings, one for
each state of the 3-state box, to display immediately to the
right of the 3-state box.

SIZE <nWidth>,<nHeight> is the width and height of the
prompt.  If the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based numbers.

MESSAGE <bcMsg> is the message you want to display in the
message area of the dialogue screen defined by the DCMESSAGEBOX
command when the object is in focus.  Optionally, INTO <oMsgBox>
will designate which message box to display the message into.
If the INTO clause is not used, then the last message box in the
GetList is the default.  <oMsgBox> may also be any object that
supports the :setCaption() method.  If <bcMsg> is a code-block,
it must return a character string.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the object will be disabled and grayed.
If the value returned is .TRUE. then the object will be enabled.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.

EDITPROTECT <bProtect> is an optional condition tested during the
execution of the GUI gets by the DCREAD GUI command, before the
object receives input focus (before it is activated). When the
condition returns the value .T. (true), the object receives the
input focus.  Otherwise, it is skipped. <bProtect> is a code
block that must return a logical value when evaluated. The object
is passed to the code block prior to the object receiving input
focus. This clause behaves similar to the WHEN clause with the
exception that the object is not disabled (grayed out).

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

VALID <bValid> is an optional condition tested during the
execution of the GUI gets by the READ command before a Get
object loses input focus (before it is deactivated).  When
the condition returns the value .T. (true), the Get object
loses the input focus.  Otherwise, it remains active. <bValid>
is a code block that must return a logical value when it is
evaluated.  The Get object is passed to the code block prior
to the Get object losing input focus.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object. If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

DATALINK <bLink> is an optional code block that is evaluated
every time Get/Set codeblock is evaluated, ie when the data
is read from the <uVar> into the object, except when using
a user-defined Get/Set code block.  <bLink> is also
evaluated when DC_GetRefresh() is called unless the <lDataLink>
parameter of DC_GetRefresh() is .FALSE.

FONT <cFont> is a character string defining an optional font.
The font string must conform to the Xbase++ standard, ie.
"10.Courier Bold". It may also be a font object or a code block
that returns a character string or a font object to later
refresh with DC_GetRefresh().

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the CheckBox object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.

TOOLTIP <bcToolTip> is a character string which will display
as a "Tool Tip" next to the object when the cursor is passed
over the object. A semi-colon within the text indicates a new
line.  If <bcToolTip> is a code-block, it must return a character
string.  NOTE: The Tooltip painting method is run in another
thread, therefore the codeblock should not run code that points
to the current work area.  It may however, contain local, public
or private variables.

CURSOR <nCursor> is an optional mouse pointer to use for this
object.  System mouse pointers start with XBPWINDOW_POINTERTYPE_
and are defined in XPB.CH.  The default pointer is
XBPWINDOW_POINTERTYPE_POINTER.  <nCursor> may also be a resource
ID that points to a Bit-Map that has been compiled with the
resource compiler and linked to the .EXE.

COLOR <bncFGc>, <ncBGc> are foreground and background colors.
They may be character strings representing valid text-based
colors supported by SetColor() or they may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH.  IF <bncFGc> is a
code block is must return a 2-element array containing a
foreground and background color.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

  [1] - A numeric value that is a pointer to the Getlist array
        for this object.

  [2] - A pointer to the GetList array.

  [3] - The value of <xCargo>.

  [4] and up - optional values added by the GUI reader.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

ACCELKEY <anAccel> is a numeric "hot-key" assignment that will set
focus to the checkbox object when the hot-key is pressed.  The key
must be a valid key with the prefix xbeK_*.  These keys are
defined in APPEVENT.CH.  <anAccel> may also be an array of numeric
values to assign more than one key to the object.

GOTFOCUS <bGotFocus> is a code block that is evaluated when this
object receives input focus.

LOSTFOCUS <bLostFocus> is a code block that is evaluated when this
object loses input focus.

TABSTOP will cause the object (Xbase Part) to be set when using
the Tab key.  Note: When logical groups are defined in a dialog
using TABGROUP <nTabGroup>, TABSTOP is usually set to .T. (true)
for the first dialog element in the group.  This allows the first
dialog element of a group to be activated using the Tab key.

NOTABSTOP will cause the object (Xbase Part) to be ignored when
using the Tab key. This clause is needed only to override any
default setting of TabStop by the DCGETOPTIONS [TABSTOP] command.

TABGROUP <nTabGroup> allows objects (Xbase Parts) that are created
immediately after one another in the GetList to be combined into
logical groups. This allows the user to navigate within a dialog
from group to group by pressing the Tab key.  Within a group of
dialog elements navigation is performed using the cursor keys.

Only constants defined in the XBP.CH file can be used as values
for this instance variable.  The following table lists the
available constants:

#define constants for <nTabGroup>:

  Constant             Description

  XBP_NO_GROUP     *)  Dialog element does not belong to a group
  XBP_BEGIN_GROUP      Dialog element is the first in a group
                       (this begins the definition of the group)
  XBP_WITHIN_GROUP     Dialog element is within a group
  XBP_END_GROUP        Dialog element is the last in a group
                       (this ends the definition of the group)

 *) Default value

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS

HELPCODE <cHelp> is a character string that is passed to the
DC_HelpF1() function if F1 is pressed or the HELP button
is clicked when this object has focus.  This HELPCODE allows
the Help system to override the passing of the Procedure and
Varname for more specific context-help.

RESIZE <aResize> is an optional array of two (2) elements
used for resizing and repositioning the object when the parent
is resized.

NOTE: RESIZE is to be used in conjunction with the RESIZE clause
      of DCGETOPTIONS. See the RESIZE clause of DCGETOPTIONS for
      examples.

      The optional SCALEFONT clause will automatically scale the
      font size up or down when the object is resized.

DRAG <bDrag> is a codeblock to evaluate when the left mouse button
is clicked in the object and the drag is started.  The return
value of the code block will be stored in memory to be later
retrieved by the Drop operation. A pointer to the clicked on
object is passed to the code block.

DIALOG <bDD> is a codeblock that will evaluate when the drag is
started.  This is used to call a function that will create a
dialog window which will move with the mouse during the drag.
The dialog window will be destroyed upon the drop operation
or the release of the mouse.

Ex: DRAG {|o|o:getData()} DIALOG {|mp1,mp2,oXbp|DragDialog(mp1,mp2,oXbp)} ;

DROP <bDrop> is a codeblock to evaluate when the left mouse button
is released in the object and the drag is ended.  A pointer to
the object and the value stored in memory at the start of the
Drag are passed to the code block.

CURSOR <nDropCursor> is the mouse cursor that will show when it
is moved over this object during a drag operation.

Ex: DROP {|o,x|o:setData(x),o:invalidateRect()} ;
       CURSOR CURSOR POINTER_DATADROP_ASSIGN

SUBCLASS <cSubClass> is a string containing a class name that
will be used to create the class, rather than DC_XbpTabPage().
This class should inherit from DC_XbpTabPage().
See the example in \exp19\samples\subclass.

Notes:

The 3-state object created by @ DC3STATE is an object of the DC_Xbp3State() class which inherits from Xbp3State(), therefore it can be manipulated with any iVar or method supported by Xbp3State().

Examples:

 #include "dcdialog.ch"

 FUNCTION Xtest()

 LOCAL GetList := {}, aForSale, nForSale := 0, oMsgBox

 aForSale := { 'Not for Sale','For Sale','Not Sure' }

 @ 2,2 DC3STATE nForSale PROMPT aForSale ;
   SIZE 12 ;
   TABSTOP ;
   MESSAGE 'Is this article FOR SALE?' INTO oMsgBox ;
   TITLE '3-STATE - For Sale?' ;
   ID 'FOR_SALE'

 @ 4,2 DCMESSAGEBOX OBJECT oMsgBox SIZE 20,1

 DCREAD GUI FIT ADDBUTTONS

 RETURN nil

Files:

DCDIALOG.CH


@ DCACTIVEXCONTROL

Create an ActiveX object for displaying with GUI reader

The command @..DCACTIVEXCONTROL creates an ActiveX object and adds the object to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> @..DCACTIVEXCONTROL objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCRADIO, @..DCPUSHBUTTON or @..DCMULTILINE.<br><br>

Syntax:

@ <nRow>,<nCol> DCACTIVEXCONTROL <oObject> ;
    [CLSID <cClsID>] ;
    [SIZE <nWidth>, <nHeight>] ;
    [PARENT <oParent>] ;
    [PARENTID <cParentId>] ;
    [CARGO <xCargo>] ;
    [HIDE <bHide>] ;
    [PRESENTATION <aPres>] ;
    [PIXEL] ;
    [PREEVAL <bPreEval>] ;
    [POSTEVAL <bPostEval>] ;
    [RELATIVE <oRel>] ;
    [ID <cId>] ;
    [TITLE <cTitle>] ;
    [TABSTOP]  ;
    [NOTABSTOP];
    [TABGROUP <nTabGroup>] ;
    [VISIBLE] ;
    [INVISIBLE] ;
    [GROUP <cGroup>] ;
    [RESIZE <aResize>] ;
    [LICENSE <cLicense>]
 ;

    [SUBCLASS <cSubClass>] ;
    [REGISTER <cClsId>, <cOcx> [USERPROMPT]]

Arguments:

<nRow>, <nCol> are the coordinates on the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE <oRel> argument is
used.  If no parent is assigned, then the parent is the Dialog
box.  IF the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel
mode by including PIXEL as a command argument.

OBJECT <oObject> is the name of the variable to assign as a
storage place for this object.

CLSID contains the id of a COM/ActiveX class an application
wants to obtain an instance of. The class ids of the COM/ActiveX
class installed on a computer are stored in the registry.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

SIZE <nWidth>, <nHeight> defines the size of the object.
If no size is given, then the object will be automatically
sized to fit the caption.  IF the PIXEL option is set to .TRUE.
in DCGETOPTIONS, then the numbers are in pixels otherwise they
are in standard text-based coordinates.  You can also force the
pixel mode by including PIXEL in the command.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object. If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the Static object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

POSTEVAL <bPostEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.
The object is passed as a parameter to the code block.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS

RESIZE <aResize> is an optional array of two (2) elements
used for resizing and repositioning the object when the parent
is resized.

NOTE: RESIZE is to be used in conjunction with the RESIZE clause
      of DCGETOPTIONS. See the RESIZE clause of DCGETOPTIONS for
      examples.

LICENSE <cLicense> is an license string required by the ActiveX
control developer.

SUBCLASS <cSubClass> is a string containing a class name that
will be used to create the class, rather than DC_XbpActiveXControl().
This class should inherit from DC_XbpActiveXControl().
See the example in \exp19\samples\subclass.

REGISTER <cClsid>, <cOcx> is the CLSID and OCX name respectively.
This clause can be used to automatically register an OCX if it has
not already been registered.  USERPROMPT will prompt the user if
the OCX failed to register.

Notes:

The object created by @ DCACTIVEXCONTROL is an object of the XbpActiveXControl() class, therefore it can be manipulated with any iVar or method supported by XbpActiveXControl().

Examples:

See the example in SAMPLES\ACTIVEX\ACROBAT.PRG.

Files:

DCDIALOG.CH

See Also:

   @ DCHTMLVIEWER


@ DCAPPCRT

Create an APPLICATION CRT object for displaying with GUI reader

The command @..DCAPPCRT creates a new Application CRT object and adds the object to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> A DCAPPCRT object is based on the XbpCrt class which is the GUI dialog used for applications partially programmed in text mode. An XbpCrt object provides a dialog window for text based and graphic oriented screen output. Using XbpCrt objects, applications programmed for text mode can be transitioned into pure PM applications in a stepwise. manner. An XbpCrt object can display text output using functions such as QOut() or DispOut() and can display Get data entry fields (command @... SAY... GET). They can also include graphic dialog elements such as those provided by objects of the XbpPushButton and XbpMLE classes. XbpCrt objects create what are called "hybrid" applications because they combine text and graphic oriented screen output. <br><br> The DCAPPCRT object offers a straightforward way to transition existing text mode applications into GUI applications which use the eXPress++ dialog system. An existing CA-Clipper application can run in an XbpCrt window after being compiled with Xbase++. The program code can be changed to use Xbase Parts that provide graphic dialog elements step by step as time permits. <br><br> @..DCAPPCRT objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCRADIO, @..DCPUSHBUTTON or @..DCMULTILINE.

Syntax:

@ <nRow>,<nCol> DCAPPCRT <oCrt> ;
  [SIZE <nHeight> [,<nWidth>]] ;
  [PARENT <oParent>] ;
  [PARENTID <cParentId>] ;
  [CAPTION <cCaption>] ;
  [BORDER <nB>] ;
  [FONT <bocFont>] ;
  [FONTSIZE <nFW>,<nFH>] ;
  [ACTION <bAction>] ;
  [COLOR <bncFgC> [,<ncBgC>] ] ;
  [CARGO <xCargo>] ;
  [THREAD <oThread>] ;
  [HIDE <bHide>] ;
  [PREEVAL <bPreEval>] ;
  [EVAL <bEval>] ;
  [PIXEL] ;
  [RELATIVE <oRel>]

Arguments:

<nRow>, <nCol> are the coordinates on the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE <oRel> argument is
used.  If no parent is assigned, then the parent is the Dialog
box.  IF the PIXEL option is set to .TRUE. in DCGET OPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel mode by
including PIXEL as a command argument.

<oCrt> is a local memory variable that will be used to store
the reference to the CRT object.

SIZE <nHeight> ,<nWidth> are the number of rows and
columns.  The default is 25 rows by 80 columns.

PARENT <oParent> is the name of the variable that was
assigned to the parent TABPAGE or GROUP for this CRT Object.
Only  use this command if you are placing this Browse onto
another dialogue object.  If this argument is not passed then
the parent will be the object set with the DCSETPARENT command. .

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

CAPTION <cCaption> is the title to display in the title
line of the CRT window.

BORDER <nB> defines the border type of a CRT window. Constants
defined in the XBP.CH file can be assigned to this instance
variable. The following table shows the valid #define constants
for BORDER .

Constants for border types

 Constant                           Description
 --------------------------         ---------------------------
 XBPDLG_NO_BORDER                    No border
 XBPDLG_SIZEBORDER                   Window is sizeable
 XBPDLG_THINBORDER               *)  Thin border, window size
                                     can not be changed
 XBPDLG_DLGBORDER                    Thick border, window size
                                     can not be changed
 XBPDLG_RAISEDBORDERTHICK       **)  Thick, raised border

 XBPDLG_RAISEDBORDERTHIN         *)  Thin, raised border
 XBPDLG_RECESSEDBORDERTHICK          Thick, recessed border
 XBPDLG_RECESSEDBORDERTHIN       *)  Thin, recessed border
 XBPDLG_RAISEDBORDERTHICK_FIXED      Thick, raised border,
                                     size can not be changed
 XBPDLG_RAISEDBORDERTHIN_FIXED   *)  Thin, raised border,
                                     size can not be changed

 XBPDLG_RECESSEDBORDERTHICK_FIXED    Thick, recessed border,
                                     size can not be changed
 XBPDLG_RECESSEDBORDERTHIN_FIXED *)  Thin, recessed border,
                                     size can not be changed

*) not supported by Windows    **) Default border

FONT <cFont> sets the font for the text based display of
characters in the CRT window. <cFont> is a character expression
specifying the name of the font. The default value is
"Alaska CRT". It may also be a font object or a code block
that returns a character string or a font object to later
refresh with DC_GetRefresh().

If the requested font is not available, the font that provides
the "best fit" is installed.

FONTSIZE <nFW>,<nFH> is the Width and Height of the font.

<nFW> sets the width of characters output in text mode (such as
output by QOut() or @... SAY). The default value is 8.  The font
width multiplied by the number of columns :maxCol+1 determines the
width of the CRT window on the screen. The calculation is
<nFW> * (:maxCol+1) == :xSize . The translation of text mode column
coordinates to graphic x coordinates is done using <nFW>.

<nFH> is used to set the font height for characters output in the
text mode (such as output by QOut() or @... SAY). The default
value is 16. The font height is multiplied by the number of
rows :maxRow+1 to determine the height of the CRT window on the
screen. The calculation used is  <nFH> * (:maxRow + 1) == :ySize.
Translating row coordinates in the text mode to graphic y
coordinates is also performed using <nFH>.

NOTE: <nFW> and <nFH> are used to select a font with the
corresponding character width and height.  This is done by the
methods :create() and :configure() . If the corresponding font is
not available, the font that provides the "best fit" is installed.

ACTION <bAction> is the program to run in the CRT window when
it is brought into focus.  If the program is to be run in
another thread, then the THREAD <oThread> option must be used
to start the application immediately in a new thread. <oThread>
is the name of a local variable to store a reference to the
thread object.

COLOR <bncFgC>,<ncBgC>] is a default color to clear the CRT
application screen.  The color string must conform to the colors
supported by SetColor().

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the <oCrt>:cargo exported variable, however
it will not be stored in the same manner it is entered.  The
:cargo container of DCDIALOG objects is an array of at least
two elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - The value of <xCargo>.

 [3] and up - optional values added by the GUI reader.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nRow>, <nCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.

Notes:

The browse object created by @ DCAPPCRT is an object of the XbpCrt() class, therefore it can be manipulated with any iVar or method supported by XbpCrt().

Files:

DCDIALOG.CH


@ DCBARGRAPH

A command for creating vertical or horizontal bar graphs

The command @..DCBARGRAPH creates a new Bar Graph definition and adds it to the array named GETLIST which is later processed by the DC_Read*() functions or by the DCREAD * commands. The GETLIST array must be first declared and initialized to the value of {}. <br><br> The command DCREAD GUI creates the DC_BarGraph() object from other DC_Xbp*() objects and activates the edit mode for all definitions found in the GetList array.<br><br> A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> @..DCBARGRAPH objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCCHECKBOX, @..DCRADIO, @..DCBUTTON, @..DCTABPAGE, @..DCTABLE or @..DCHTML*.

Syntax:

@ <nRow> [, <nCol>] DCBARGRAPH                   ;
         [TYPE <nType>]                        ;
         [DATA <aArray>]                       ;
         [PARENT <oParent>]                    ;
         [PARENTID <cParentID>]                ;
         [BGCOLOR <abnBgColor>]               ;
         [TEXTFONT <cTextFont>]                ;
         [TEXTCOLOR <abnTextfgC> [,<abnTextbgC>]]    ;
         [SCALEFONT <cScaleFont> ]              ;
         [SCALECOLOR <abnScalefgC> [,<abnScalebgC>] ] ;
         [BARCOLOR <aBarColor>]                ;
         [LBDOWN <bLbDown>]                    ;
         [RBDOWN <bRbDown>]                    ;
         [MAXVALUE <nMaxValue>]                ;
         [MINVALUE <nMinValue>]                ;
         [SCROLLBUTTONS]                       ;
         [SCROLLRANGE <nScrollRange>]          ;
         [SIZE <nWidth> [,<nHeight>]]         ;
         [EVAL <bEval>]                        ;
         [PREEVAL <bPreEval>]                  ;
         [RELATIVE <oRel>]                     ;
         [OBJECT <oObject>]                    ;
         [ID <cId>]                            ;
         [TITLE <title>]                       ;
         [VISIBLE]                             ;
         [GROUP <cGroup>]                      ;
         [LINEMARKERS <aLineMarkers>]

Arguments:

<nRow>, <nCol> are the coordinates on the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE <oRel> argument is
used.  If no parent is assigned, then the parent is the Dialog
box.  IF the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel mode by
including PIXEL as a command argument.

TYPE <nType> is the type of bargraph to create.  <nType> is a
numeric value starting with DCGRAPH_TYPE_* as defined in DCGRAPH.CH.

Type                       Description
-------------------------- ------------------------------------
DCGRAPH_TYPE_VERTICAL      Vertical bars
DCGRAPH_TYPE_HORIZONTAL    Horizontal bars

DATA <aData> is an array containing the numeric information and
text information for graphing.  Each element of the array is a
sub-array of up to 4 elements as defined in the below table.

Element Type    Description
------- ------- -----------------------------------------------
  [1]   N,A     Data to graph.  May be a numeric value for graphs
                with only 1 bar or an array of numeric values for
                graphs with 2 or more bars in each group.

  [2]   C       Text prompt for the bar group.

  [3]   C,B     Text ToolTip.  This is a tooltip to display when
                the mouse is moved over the text that defines
                each bar group.

  [4]   C,A,B   Bar ToolTip. This is a tooltip to display when the
                mouse is moved over the bar.  If element 1 is an
                array, then this element must also be an array of
                equal length.  If this element is a NIL, then the
                tooltip will be the numeric value of the bar.

  [5]   N,A,B   Bar Color. This is the color of the bar.  If element 1
                is an array, then this element must also be an array
                of equal length.  If this element is a NIL, then the
                default will be establish by the BARCOLOR clause.

  [6]   A       Marker Line.  This is a 2-element array containing:
                [1] the numeric location of the marker on the bar and
                [2] the numeric color of the marker.  This will paint
                a marker line on the bar.  If element 1 is an array
                this this element must also be an array of equal
                length containing sub-arrays of 2 elements.

SIZE <nWidth>,<nHeight> is the width and height of the
graph.  If the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based numbers.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.  If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

OBJECT <oObject> is the variable to use as a container for the
DC_BarGraph() object after it is created by the GUI reader.

BGCOLOR <abnBgColor> is the color of the background for the bar
area of the graph.  <abnBgColor> may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH.  It may also be a
3-element array containing numeric values equivalent to RBG
colors.  It may also be a code block that returns a numeric
value or a 3-element array.

TEXTFONT <cTextFont> is a character string defining an optional
font for the text defining each bar group.  The font string must
conform to the Xbase++ standard, ie. "10.Arial Bold". It may also
be a font object or a code block that returns a character string
or an XbpFont() font object.

SCALEFONT <cScaleFont> is a character string defining an optional
font for the scale text.  The font string must conform to the
Xbase++ standard, ie. "10.Arial Bold". It may also be a font
object or a code block that returns a character string or an
XbpFont() font object.

TEXTCOLOR <abnTextfgC>, <abnTextBgC> are foreground and background
colors for the text defining each bar group. They may be character
strings representing valid text-based colors supported by SetColor()
or they may be numeric constants which begin with either the prefix
GRA_CLR_ or the prefix XBPSYSCLR_ as defined in GRA.CH or XBP.CH
or they may be 3-element arrays containing numeric RGB values or
they may be codeblocks that return a numeric value or an RGB array.

SCALECOLOR <abnScalefgC>, <abnScaleBgC> are foreground and background
colors for the scale text. They may be character strings representing
valid text-based colors supported by SetColor() or they may be
numeric constants which begin with either the prefix GRA_CLR_ or the
prefix XBPSYSCLR_ as defined in GRA.CH or XBP.CH or they may be
3-element arrays containing numeric RGB values or they may be
codeblocks that return a numeric value or an RGB array.

BARCOLOR <aBarColor> is an array of bar colors.  This array must
be the same length as element 1 of <aData>.  Each element of this
array may be a numeric color or a sub-array of 3 numeric RGB values.

LBDOWN <bLbDown> is a code block to evaluate when the left mouse is
clicked in the bar area of the graph.  The code block receives two
values: 1. the numeric value of the bar group and 2. the numeric
value of the sub group.

RBDOWN <bRbDown> is a code block to evaluate when the right mouse is
clicked in the bar area of the graph.  The code block receives two
values: 1. the numeric value of the bar group and 2. the numeric
value of the sub group.

MAXVALUE <nMaxValue> is the highest positive value to be graphed.
If the data exceeds this value, the bar will be truncated in the
display.  If this clause is not used, then the maximum value will
default to the highest value in the <aData> array.

MINVALUE <nMinValue> is the lowest negative value to be graphed.
If the data exceeds this value, the bar will be truncated in the
display.  If this clause is not used, then the minimum value will
default to the lowest value in the <aData> array.

SCROLLBUTTONS will paint a set of buttons on the graph to be used
for scrolling the graph data within the window.  This clause
should be used when the scrolling range is less than the length
of the data array.

SCROLLRANGE <nScrollRange> is the number of bar groups to display
in the window.  This should always be less than the length of the
data array.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

OBJECT <oObject> is the variable to use as a container for the
object after it is created by the GUI reader.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

  [1] - A numeric value that is a pointer to the Getlist array
        for this object.

  [2] - A pointer to the GetList array.

  [3] - The value of <xCargo>.

  [4] and up - optional values added by the GUI reader.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

LINEMARKERS <aLineMarkers> is an array of sub-arrays defining
lines to be drawn across the graph at specified values.
Each sub-array contains 2 elements:

  Element  Type   Description
  -------  ----   --------------------------------------------
    [1]     N     Value on graph to draw line.
    [2]     N,A   Color of line (GRA_CLR_*) or 3-element array
                  containing RGB colors.

Notes:

The bargraph object created by @ DCBARGRAPH is an object of the DC_BarGraph() class which is made up of child elements of the DC_XbpStatic() and DC_XbpPushButton() classes.

Examples:

#include "dcgraph.ch"

FUNCTION SalesGraph()

LOCAL i, aCaption, aBarColor, aData, oGraph, GetList[0], bLbDown, GetOptions, ;
      oStaticText, oStaticGraph, aGraphData[0], nYear := 2000

aData := { ;
   { {10,-12,40},  ;
     {22,16,20},   ;
     {25,35,11},   ;
     {20,25,88},   ;
     {33,50,-99},  ;
     {45,22,16},   ;
     {57,90,77},   ;
     {31,-44,55},  ;
     {21,60,32},   ;
     {51,11,28},   ;
     {66,30,-19},  ;
     {62,49,73} }, ;
   { {39,-52,50},  ;
     {52,28,30},   ;
     {75,25,31},   ;
     {10,15,-28},   ;
     {63,20,29},  ;
     {35,-72,56},   ;
     {27,-30,37},   ;
     {51,14,-65},  ;
     {21,40,32},   ;
     {61,21,-18},   ;
     {46,40,29},  ;
     {32,59,23} }, ;
   { {20,-2,30},   ;
     {32,6,10},    ;
     {15,25,1},    ;
     {10,15,78},   ;
     {23,40,-89},  ;
     {35,12,6},    ;
     {47,80,67},   ;
     {21,-34,45},  ;
     {11,50,22},   ;
     {41,1,18},    ;
     {56,20,-9},   ;
     {52,39,63} } }

nYear := 2000
_GetGraphData( aGraphData, @nYear, aData )

bLbDown := {|a,b|DC_DebugQOut({aGraphData[a,1,b]})}

aCaption := { 'Sales','Expenses','Profit' }
aBarColor := { GRA_CLR_BLUE, GRA_CLR_DARKPINK, GRA_CLR_GREEN }

@ 0,0 DCSTATIC TYPE XBPSTATIC_TYPE_TEXT ;
      SIZE 100,4 OBJECT oStaticText ;
      COLOR GRA_CLR_BLACK, GRA_CLR_WHITE

@ .5,40 DCSAY {||'Year ' + Alltrim(Str(nYear))} SAYSIZE 20,2 FONT '18.Arial Bold' ;
      COLOR GRA_CLR_BLACK, GRA_CLR_WHITE GROUP 'GRAPH'

FOR i := 1 TO Len(aCaption)
  @ 2.5,i*20 DCSAY aCaption[i] COLOR aBarColor[i] SAYSIZE 0 ;
    FONT '14.Arial Bold' PARENT oStaticText
NEXT

@ 4,0 DCSTATIC TYPE XBPSTATIC_TYPE_TEXT ;
      SIZE 100,20 OBJECT oStaticGraph ;
      COLOR GRA_CLR_BLACK, GRA_CLR_WHITE

@ 0,0 DCBARGRAPH ;
      SIZE 100,20 ;
      DATA aGraphData ;
      RBDOWN bLbDown ;
      LBDOWN bLbDown ;
      TEXTFONT '12.Arial Bold' ;
      SCALEFONT '8.Arial Bold' ;
      TEXTCOLOR GRA_CLR_BLACK ;
      SCALECOLOR GRA_CLR_BLACK ;
      BARCOLOR aBarColor ;
      TYPE DCGRAPH_TYPE_VERTICAL ;
      SCROLLRANGE 6 ;
      SCROLLBUTTONS ;
      FONT '18.Arial Bold' ;
      BGCOLOR GRA_CLR_YELLOW ;
      PARENT oStaticGraph ;
      OBJECT oGraph

@ 25,0 DCPUSHBUTTON CAPTION 'Prev Year' SIZE 11,1.2 ;
      ACTION {||nYear--,_GetGraphData(aGraphData,@nYear,aData), ;
                oGraph:refresh(), DC_GetRefresh(GetList,,,,'GRAPH')} ;
      WHEN {||nYear򗶰} TOOLTIP 'Graph Previous Year' ;
      GROUP 'GRAPH'

@ 25,13 DCPUSHBUTTON CAPTION 'Next Year' SIZE 11,1.2 ;
      ACTION {||nYear++,_GetGraphData(aGraphData,@nYear,aData), ;
                oGraph:refresh(), DC_GetRefresh(GetList,,,,'GRAPH')} ;
      WHEN {||nYear򒾒} TOOLTIP 'Graph Next Year' ;
      GROUP 'GRAPH'

DCGETOPTIONS ;
    AUTORESIZE ;
    TOOLTIPCOLOR GRA_CLR_BLACK, GRA_CLR_CYAN ;
    TOOLTIPFONT '12.Courier'

DCREAD GUI FIT OPTIONS GetOptions TITLE 'Graph of Sales (2000-2002)'

RETURN nil

* -------------

STATIC FUNCTION _GetGraphData( aGraphData, nYear, aData )

LOCAL i, nPointer := nYear-1999, aMonths

aMonths := {'Jan','Feb','Mar','Apr','May','Jun','Jul', ;
            'Aug','Sep','Oct','Nov','Dec'}

ASize(aGraphData,0)

FOR i := 1 TO 12
  AAdd(aGraphData, { aData[nPointer,i], aMonths[i] } )
NEXT

RETURN nil

Files:

_DCGRAPH.PRG, DCGRAPH.CH, DCLIPX.DLL

See Also:

   dc_bargraph()


@ DCBROWSE

Create a BROWSE object for displaying with GUI reader

The command @..DCBROWSE creates a new Browse definition and adds it to the array named GETLIST which is later processed by the DC_Read*() functions or by the DCREAD * commands. The GETLIST array must be first declared and initialized to the value of {}. <br><br> The command DCREAD GUI creates the DC_Xbp*() objects and activates the edit mode for all definitions found in the GetList array.<br><br> The command DCREAD HTML creates the DC_Html*() objects and writes the HTML source code.<br><br> A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> A DCBROWSE object is a parent to DCBROWSECOL objects (the columns of the browse). DCBROWSE is used to browse either arrays or databases.<br><br> @..DCBROWSE objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCCHECKBOX, @..DCRADIO, @..DCBUTTON, @..DCTABPAGE, @..DCTABLE or @..DCHTML*.<br><br> The command is broken into 2 sections to prevent problems with the Microsoft Help Compiler. See @ .. DCSAY .. GET (2)

Syntax:

@ <nRow>, <nCol> DCBROWSE <oBrowse> ;
    [DATA <aoData> [ELEMENT <nElement>] ] ;
    [ALIAS <cAlias>] ;
    [SIZE <nWidth> [,<nHeight>]] ;
    [PARENT <oParent>] ;
    [PARENTID <cParentId>] ;
    [INTO <aVar>] ;
  * [POINTER <nVar>] ;
  * [DATALINK <bLink>] ;
  * [PRESENTATION <aPres>] ;
  * [CURSORMODE <nCursorMode>] ;
    [COLOR <bncFgC> [,<ncBgC>] ] ;
    [CARGO <xCargo>] ;
  * [PIXEL] ;
    [MESSAGE <bcMsg> [INTO <oMsgBox>]] ;
    [HIDE <bHide>] ;
    [WHEN <bWhen>] ;
  * [RBSELECT] ;
    [PREEVAL <bPreEval>] ;
    [EVAL <bEval>] ;
    [FONT <bocFont>] ;
  * [EDIT <nEditEvent> | <aEditEvent> ;
       [ MODE <nbEditMode>] ;
       [ ACTION <bEditAction>] ;
       [ EXIT <bEditExit> ] ] ;
  * [INSERT <nInsertEvent> ;
       [ INSMODE <nInsMode> ] ;
       [ DEFAULT <abDefault>] ;
       [ ACTION <bInsertAction>] ;
       [ EXIT <bInserExit>] ] ;
       [ APPEND <nAppendEvent>] [ APPMODE <nAppMode> ] ];
  * [DELETE <nDeleteEvent> ;
       [ ACTION <bDeleteAction>] ;
       [ EXIT <bDeleteExit> ] ] ;
  * [HANDLER <handler> [REFERENCE <xRef>]] ;
    [RELATIVE <oRel>] ;
  * [ITEMMARKED <bItemMarked>] ;
  * [ITEMSELECTED <bItemSelected>] ;
  * [MARK <nbMark>] ;
  * [MKCOLOR <nbMarkEval>, <nMFgC> [,<nMBgC>] ] ;
    [ID <cId>] ;
  * [FREEZELEFT <aColLeft>  ;
  * [FREEZERIGHT <aColRight>] ;
  * [ACCELKEY <nKey>] ;
  * [GOTFOCUS <bGotFocus>] ;
  * [LOSTFOCUS <bLostFocus>] ;
  * [TABSTOP] ;
  * [NOTABSTOP];
  * [TABGROUP <nTabGroup>] ;
  * [VISIBLE] ;
  * [INVISIBLE] ;
    [SCOPE] ;
  * [THUMBLOCK <nbThumbLock>] ;
  * [NOVSCROLL] ;
  * [NOHSCROLL] ;
  * [NOSOFTTRACK] ;
  * [NOSIZECOLS] ;
    [GROUP <cGroup>] ;
  * [HEADLINES <nHeaderLines> [DELIMITER <cHeadDelim>]] ;
  * [FOOTLINES <nFooterLines> [DELIMITER <cFootDelim>]] ;
  * [FIT [MAX <nMaxFitWidth>]] ;
  * [OPTIMIZE] ;
    [TITLE <cTitle>] ;
  * [AUTOREFRESH <nTimer> [REFRESHBLOCK <bRefresh>] ;
       [WHEN <bRefreshWhen>]] ;

  ... MORE Clauses ( See @ DCBROWSE (2) )

Arguments:

GUI applications:

<nRow>, <nCol> are the coordinates on the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE <oRel> argument is
used.  If no parent is assigned, then the parent is the Dialog
box.  IF the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel mode by
including PIXEL as a command argument.

HTML applications:

<nRow> and <nCol> are the row number and column number of
the table if the parent of this object is a DCTABLE. The
text will be inserted in the cell of the table defined by
the row/column.

<oBrowse> is the name of the variable to assign as a storage
place for this object.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

ALIAS <cAlias> defines the browse as a database browse. <cAlias)
is a variable containing the alias of the database to browse.

  or

DATA <aoData> defines the browse as an array browse or an object
browse.  <aoData> is a variable containing a pointer to the
array to or object to browse.  ELEMENT <nElement> is an optional
clause defining the selected element of if <aoData> is an array.
CAUTION: If a new array pointer is created that points to a
different array, then DC_GetBrowArray() must be used to update
the array pointer in the browse object.

If <aoData> is an object, then it must conform to one of the
following classes:

SQLStatement - SQLExpress
SQLDataSet - SQLExpress
dsACEServer - ACE Server
dbfServer - DBFSERVER
spSql - SPSQL Server

SIZE <nWidth>,<nHeight> is the width and height of the
prompt.  If the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based numbers.

INTO <aVar> is a memory variable to store a sub-array. This clause
is used only when browsing arrays.  Each time the user clicks on
a new row of the array browse, the sub-array selected will be
stored in <aVar>.  <aVar> must be initialized to an array.

POINTER <nVar> is a memory variable to store the current array
element pointer. This clause  is used only when browsing arrays.
Each time the user clicks on a new row of the array browse, the
browse row (element number) will be stored in <nVar>.  <nVar>
must be initialized to a numeric value.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.  If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

DATALINK <bDataLink> is an optional code block to evaluate
whenever the user double-clicks the mouse or presses the ENTER key
within the browse area.  The browse object is passed as a
parameter to the code block.

FONT <cFont> is a character string defining an optional font.
The font string must conform to the Xbase++ standard, ie.
"10.Courier.Bold". It may also be a font object or a code block
that returns a character string or a font object to later
refresh with DC_GetRefresh().

EDIT <nEditEvent> is an optional clause that enables "cell-editing"
of the browse cells whenever a specified event occurs that is
associated with the browse object.  <nEditEvent> is a numeric
value equivalent to an xbe* event or keyboard value which has
been defined in APPEVENT.CH.  For example, cell editing will
occur within the selected cell when <nEditEvent> is equal to
xbeBRW_ItemSelected and the cell is selected with a mouse
double-click or the ENTER key is pressed.  MODE <nbEditMode> is
the navigation mode within the cells.  <nbEditMode> is a numeric
value from the below table.  If <nbEditMode> is a codeblock then
it must return a numeric value.

  <nEditMode>                 Description
  -----------                 ------------------------------------
  DCGUI_BROWSE_EDITEXIT       Exit cell editing after ENTER key

  DCGUI_BROWSE_EDITACROSS     Move to next column after ENTER key

  DCGUI_BROWSE_EDITDOWN       Move to next row after ENTER key

  DCGUI_BROWSE_EDITACROSSDOWN Move to next column after ENTER key
                              and move to next row at end of column

  DCGUI_BROWSE_EDITACROSSDOWN_APPEND
                              Move to next column after ENTER key
                              and move to next row at end of column
                              Pressing ENTER at last row/last column
                              appends new element.  Pressing DOWN
                              arrow key at last row appends new
                              element.

<aEditEvent> is a 2-element array.  The first element is the
same as that described above for <nEditEvent>.  The second element
is a code block to evaluate when a key is pressed in the browse.
The value of the key pressed is passed to the code block.  The
code block must return a numeric value equivalent to the key to
enter into the cell, or an array of numeric values to enter into
the cell.  If a proper value is returned then cell editing will
start.

<bEditAction> is an optional code block that is evaluated before
the cells are edited.  <bEditExit> is an optional code block that
is evaluated after the cells are edited.  The browse object is
passed as a parameter to <bEditAction> and <bEditExit>.

INSERT <nInsertEvent> is an optional clause that enables the
inserting of an element into the array and editing the cell
items. <nInsertEvent> is a numeric value equivalent to an xbe*
event or keyboard value which has been defined in APPEVENT.CH.
For example, cell insertion will occur at the selected row of
the browse when <nEditEvent> is equal to xbeK_INS and the browse
is in focus and the INSERT key is pressed.  <bInsertAction> is an
optional code block that is evaluated before a new element is
inserted in the array.  <bInsertExit> is an optional code block
that is evaluated after exiting the cell editor.  The Browse
Object is passed as a parameter when evaluating <bInsertAction>
and <bInsertExit>.  INSMODE <nInsMode> is an additional optional
clause that can only be used with the INSERT clause.  <nInsMode>
determines the behavior of insert mode.

  <nInsMode>             Description
  -----------            ------------------------------------
  DCGUI_BROWSE_SUBMODE_1 Up/Down arrow keys are ignored.
                         Enter key on last column exits insert.

  DCGUI_BROWSE_SUBMODE_2 Up/Down arrow key will move to previous
                         or next row respectively.  If down arrow
                         pressed in last row, will append new
                         element.

APPEND <nAppendEvent> is an additional optional clause that can
only be used with the INSERT clause.  <nAppendEvent> is a numeric
value equivalent to an xbe* event or keyboard value. This event
forces the insertion of the new element at the end of the array
rather than at the selected row.  APPMODE <nAppMode> is an
additional optional clause that can only be used with the APPEND
clause.  <nAppMode> determines the behavior of append mode.

  <nAppMode>             Description
  -----------            ------------------------------------
  DCGUI_BROWSE_SUBMODE_1 Up/Down arrow keys are ignored.
                         Enter key on last column exits append.

  DCGUI_BROWSE_SUBMODE_2 Up/Down arrow key will move to previous
                         or next row respectively.  If down arrow
                         pressed in last row, will append new
                         element.

DELETE <nDeleteEvent> is an optional clause that enables the
deleting the current selected element (row) of an array or the
currently selected record. <nDeleteEvent> is a numeric value
equivalent to an xbe* event or keyboard value which has been
defined in APPEVENT.CH.  For example, cell deletion will occur
at the selected row of the browse when <nEditEvent> is equal to
xbeK_DEL and the browse is in focus and the DELETE key is pressed.
<bDeleteAction> is an optional code-block that is evaluated before
the element is deleted.  <bDeleteExit> is an optional code block
that is evaluated after the element is deleted.  The Browse Object
is passed as a parameter when evaluating <bDeleteAction> and
<bDeleteExit>.

HANDLER <cEventHandler> is the name of a Function which points
to a custom event handler.  The cell editor uses it's own, default
event handler to manage the objects during the running of the
program.  The default event handler makes a call to the
custom event handler before processing it's default events.
The custom event handler uses Appevent() to get information
on the current event and passes the following parameters:

  1. nEvent   - The event type.
  2. mp1      - The first event parameter.
  3. mp2      - The second event parameter.
  4. oXbp     - A pointer to the object creating the event.
  5. oDlg     - A pointer to the main dialogue object.
  6. aGetlist - A pointer to the GetList array.
  7. aRef     - A pointer to an optional Reference array.

  The Function should look like this:

  STATIC FUNCTION MyHandler ( nEvent, mp1, mp2, oXbp, oDlg,
                              aGetlist, aRef )

  /* custom code */

  RETURN DCGUI_NONE

 The function must return a numeric value which controls the
 behavior of the event loop as follows:

  Return Value   Behavior
  ------------   --------------------------------------------
  DCGUI_NONE     Continue processing the event
  DCGUI_IGNORE   Ignore event
  DCGUI_CLEAR    Ignore event and clear all events from queue
  DCGUI_EXIT     Exit the Cell editor

REFERENCE <aRef> is any array to pass to the custom event handler.
Programming dialogue systems that must manipulate many variables
is much simpler if all the variables are placed into a single
array and then passed to the dialogue system and its event
handler.

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the Browse object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
these are also generally set using #define constants from the
GRA.CH file.

CURSORMODE <nCursorMode> determines the browse cursor to be
displayed by the Browse object. #define constants from XBP.CH
must be used for this mode:

  Constant            Description

  XBPBRW_CURSOR_NONE  No visible cursor
  XBPBRW_CURSOR_CELL  Cell cursor (default)
  XBPBRW_CURSOR_ROW   Row cursor

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

  [1] - A numeric value that is a pointer to the Getlist array
        for this object.

  [2] - A pointer to the GetList array.

  [3] - The value of <xCargo>.

  [4] and up - optional values added by the GUI reader.

COLOR <bncFGc>, <ncBGc> are foreground and background colors.
They may be character strings representing valid text-based
colors supported by SetColor() or they may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH. IF <bncFGc> is a
code block is must return a 2-element array containing a
foreground and background color.

ITEMMARKED <bItemMarked> is a code block to evaluate when a data
row or a cell is highlighted in the browser.  The code block
must be formatted as {| aRowCol, uNIL2, self | ... } where
<aRowCol> is a two-element array { nRowPos, nColPos } which
indicates the row and column position of the cell that is
clicked with the left mouse button.

ITEMSELECTED <bItemSelected> is a code block to evaluate when
a data row is selected with a double-click of the left mouse
button or by pressing the ENTER key in the browser.  The code
block must be formatted as {| uNIL1, uNIL2, self | ... }.

MARK <nbMark> is a numeric value or a code block.  A numeric
value is used to point to the array sub-element which contains
a logical value.  When the mouse is double-clicked in a browse
column (item selected), the value in the sub-element is toggled
between .TRUE. and .FALSE.  IF a code block is entered, then
a double-click will evaluate the code block.  For example a
code block can be used to toggle the value of a logical field
in the selected record.

MKCOLOR <nbMarkEval> is an optional code block to evaluate
to display "marked" records or array elements.  This code block
must return a LOGICAL value.  When the value returned is .TRUE.,
the color of the entire row (all columns) is set to the <ncMFgC>
and <ncMBgC> colors.  When the value returned is .FALSE., each
column in the row is displayed in the color established for that
individual row.

<ncMFgC>, <ncMBgC> are foreground and background colors that
are selected when <nbMarkEval> evaluates .TRUE.  They may be
character strings representing valid text-based colors supported
by SetColor() or they may be numeric constants which begin with
either the prefix GRA_CLR_ or the prefix XBPSYSCLR_ as defined
in GRA.CH or XBP.CH.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

FREEZELEFT <aColsLeft> is an array of numeric values equal to
the position of the columns in the browse which should be frozen
at the left side of the browse window and prevented from
scrolling off the screen.  Note: Frozen columns cannot be resized.

FREEZERIGHT <aColsRight> is an array of numeric values equal to
the position of the columns in the browse which should be frozen
at the right side of the browse window and prevented from
scrolling off the screen.  Note: Frozen columns cannot be resized.

MESSAGE <bcMsg> is the message you want to display in the
message area of the dialogue screen defined by the DCMESSAGEBOX
command when the object is in focus.  Optionally, INTO <oMsgBox>
will designate which message box to display the message into.
If the INTO clause is not used, then the last message box in the
GetList is the default.  If <bcMsg> is a code-block, it must
return a character string.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the object will be disabled and grayed.
If the value returned is .TRUE. then the object will be enabled.

RBSELECT will cause the right button of the mouse to select a
browse cell in the same manner as the left button.

ACCELKEY <anAccel> is a numeric "hot-key" assignment that will set
focus to the browse object when the hot-key is pressed.  The key
must be a valid key with the prefix xbeK_*.  These keys are
defined in APPEVENT.CH.  <anAccel> may also be an array of numeric
values to assign more than one key to the object.

GOTFOCUS <bGotFocus> is a code block that is evaluated when this
object receives input focus.  <bGotFocus> := {|uNIL1,uNIL2,self|...}

LOSTFOCUS <bLostFocus> is a code block that is evaluated when this
object loses input focus. <bLostFocus> := {|uNIL1,uNIL2,self|...}

TABSTOP will cause the object (Xbase Part) to be set when using
the Tab key.  Note: When logical groups are defined in a dialog
using TABGROUP <nTabGroup>, TABSTOP is usually set to .T. (true)
for the first dialog element in the group.  This allows the first
dialog element of a group to be activated using the Tab key.

NOTABSTOP will cause the object (Xbase Part) to be ignored when
using the Tab key. This clause is needed only to override any
default setting of TabStop by the DCGETOPTIONS [TABSTOP] command.

TABGROUP <nTabGroup> allows objects (Xbase Parts) that are created
immediately after one another in the GetList to be combined into
logical groups. This allows the user to navigate within a dialog
from group to group by pressing the Tab key.  Within a group of
dialog elements navigation is performed using the cursor keys.

Only constants defined in the XBP.CH file can be used as values
for this instance variable.  The following table lists the
available constants:

 #define constants for <nTabGroup>:

  Constant             Description

  XBP_NO_GROUP     *)  Dialog element does not belong to a group
  XBP_BEGIN_GROUP      Dialog element is the first in a group
                       (this begins the definition of the group)
  XBP_WITHIN_GROUP     Dialog element is within a group
  XBP_END_GROUP        Dialog element is the last in a group
                       (this ends the definition of the group)

 *) Default value

SCOPE is an optional argument that enables the browse to display only
the records that adhere to a previous scope that has been set by
DC_SetScope().  This feature utilizes the functions DC_dbGoTop(),
DC_dbGoBottom(), DC_dbSkipper(), DC_KeyCount() and DC_KeyNo() in the
navigation code blocks of the browse to stay in scope.  In addition, the
vertical scrollbar will accurately show the record position within the
current scope.

If this argument is not used, the browse will utilize dbGoTop(),
dbGoBottom(), dbSkipper(), OrdKeyNo() and a modified RecCount() in the
navigation code blocks of the browse.  These functions will disregard any
previous settings of DC_SetScope().  Additional filtering must be
accomplished by using SET FILTER or conditional indexes.

Note: When using the DBFNTX, DBFCDX or FOXCDX drivers,the eXPress++ scoping
system can slow performance therefore it is recommended that you do not use
it on large databases unless you also use the THUMBLOCK clause.  The
eXPress++ scoping system has been designed for optimization, however, when
using third-party DBE's such as COMIX and Advantage Server and will
automatically detect that these drivers are being used.  SCOPE also utilizes
the percentage method for determining the position of the scrollbar thumb by
using the DC_KeyNo() and DC_KeyCount() functions. If the database contains
more than 32000 records the thumb is scaled to compensate for the limitation
of the XbpScrollbar class to only 32k positions. DC_KeyNo() is enabled with
DC_KeyStat(.T.).

NOTE: If DC_KeyStat() is set to .FALSE. or a Filter is set on the
      database, DC_KeyCount() will return a -1 thereby causing
      the vertical scrollbar thumb to occupy the entire scroll
      area.  It is not possible to determine the key count
      when a filter is set.

THUMBLOCK <nbThumbLock> should be used on very large databases which
are indexed or on databases that have a filter. This option forces the
thumb to remain locked in the middle of the vertical scrollbar region
to prevent the user from forcing a skip request that can take a very
long time or to move to an incorrect record when a filter is set on
the database.  If <nbThumbLock> is a numeric value and the database
contains more than <nbThumbLock> records the thumb will be locked
however the user may still click above and below the thumb for page
up/page down respectively.  The default is 32,000 records.  If
<nbThumbLock> is a numeric 0 then the thumb will be locked all the
time.  If <nbThumbLock> is a codeblock, then the codeblock must
return a logical .T. to lock the thumb or .F. to unlock the thumb.
The codeblock is evaluated with DC_GetRefresh() or oBrowse:refreshAll().

NOVSCROLL will suppress the vertical scroll bar.

NOHSCROLL will suppress the horizontal scroll bar.

NOSOFTTRACK will force movement of the scroll bars to automatically refresh
the browse while the bar is moving.

NOSIZECOLS will prevent the user from sizing columns.

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

HEADLINES <nHeaderLines> is the number of lines (rows) to use
in the column headers.  The default is 1.  DELIMITER <cHeadDelim>
is the delimiter character(s) which are used to denote the start
of a new line in the HEADER clause of DCBROWSECOL.  The default
delimiter is a semi-colon.

 Example: DCBROWSECOL HEADER 'Street Address;City/State'

FOOTLINES <nFooterLines> is the number of lines (rows) to use
in the column footers.  The default is 1.  DELIMITER <cFootDelim>
is the delimiter character(s) which are used to denote the start
of a new line in the FOOTER clause of DCBROWSECOL.  The default
delimiter is a semi-colon.

FIT will automatically size the WIDTH of the browse to the sum
of the widths of all the columns.  CAUTION: this clause only
overrides the browse width, not the height.  The SIZE clause must
still be used to set the browse height and width or a runtime error
will occur.  The MAX <nMaxFitWidth> sub clause is used to set
the maximum width of the browse.

OPTIMIZE will enable a double-click in the header column to
resize the column to the optimum width so all items will fit in
the column with no truncated items.  The OPTIMIZE clause will
only work when browsing an array.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

AUTOREFRESH <nTimer> is used to set a timer event that automatically
refreshes the browse window (when it is visible) every
<nTimer>/100 seconds.  REFRESHBLOCK <bRefresh> is an optional
code block to evaluate rather than using the default :refresh()
method.  WHEN <bRefreshWhen> is an option codeblock to evaluate
to cause the refresh to occur only when the codeblock returns a
.TRUE. value.

Notes:

Gui Applications :

The browse object created by @ DCBROWSE is an object of theDC_XbpBrowse() class which inherits from the XbpBrowse()class, therefore it can be manipulated with any iVar or method supported by XbpBrowse().

The browse navigation system for arrays looks like this.

oXbp:skipBlock := {|n,o| SkipArray( n, o:cargo ) } oXbp:goTopBlock := {|o| o:cargo[4] := 1 } oXbp:goBottomBlock := {|o| o:cargo[4] := Len( o:cargo[5] ) } oXbp:posBlock := {|o| o:cargo[4] } oXbp:phyPosBlock := {|o| o:cargo[4] } oXbp:lastPosBlock := {|o| Len( o:cargo[5] ) } oXbp:firstPosBlock := {|| 1 }

The :cargo instance variable contains an array of pointers, VALID, HIDE, WHEN and FREEZE information. When installing a custom"skipper" system, use :cargo[3] as a complete cargo sub-system.

Here is the standard CARGO convention for all objects created by DC_ReadGUI():

:cargo[1] is a pointer to the GetList number:cargo[2] is a pointer to the Getlist array:cargo[3] is USER-DEFINED cargo:cargo[4] and up are reserved.

All custom skipper methods should use pointers in cargo[3]. Acustom skipper system would be installed after the objects werecreated by DC_ReadGUI(). This can be accomplished by using theEVAL clause in the DCREAD GUI command to call a user-definedfunction.

Example:

oXbp:cargo[3] := Array(2) oXbp:skipBlock := {|n,o| MySkipArray( n, o:cargo ) } oXbp:goTopBlock := {|o| o:cargo[3,1] := 1 } oXbp:goBottomBlock := {|o| o:cargo[3,1] := Len( o:cargo[3,2] ) } oXbp:posBlock := {|o| o:cargo[3,1] } oXbp:phyPosBlock := {|o| o:cargo[3,1] } oXbp:lastPosBlock := {|o| Len( o:cargo[3,2] ) } oXbp:firstPosBlock := {|| 1 }

/* ---------------------- */

STATIC FUNCTION MySkipArray( nWantSkip, aCargo )

LOCAL nDidSkip, nLastRec := Len( aCargo[3,2] )

IF aCargo[3,1] + nWantSkip < 1 // "BoF" nDidSkip := 1 - aCargo[3,1] ELSEIF aCargo[3,1] + nWantSkip > nLastRec // "EoF" nDidSkip := nLastRec - aCargo[3,1] ELSE nDidSkip := nWantSkip ENDIF aCargo[3,1] += nDidSkip

RETURN nDidSkip

/* ------------------------- */

CAUTION: When overloading the Skipper system, you must also overload the :itemSelected instance variable. The default codeblock for :itemSelected refers to array elements in :cargo which have been previously set-up to work with the default Skipper. If the :cargo array is modified, then a double-click on a browse column will cause a runtime error.

------------------------------

HTML Applications :

The browse object created by @ DCBROWSE is an object of theDC_HtmlBrowse() class.

Examples:

 /*
 This example demonstrates both a database browse and an
 array browse in the same dialogue screen.  The database
 browse is on Tab Page 1 and the Array browse (directory
 listing) is on Tab Page 2.
 */

 #include "dcdialog.ch"
 #include "xbp.ch"

 PROCEDURE Xtest()

 LOCAL GetList := {}, GetOptions, oTabPage1, oTabPage2, ;
       oBrowse, cAlias, aDirectory, oDirectory

 USE COLLECT NEW SHARED

 /* ---- Tab Page #1 ---- */

 @ 3,3 DCTABPAGE oTabPage1 CAPTION 'Browse' ;
   SIZE 60,12

 cAlias := "COLLECT"

 @ 2,2 DCBROWSE oBrowse PARENT oTabPage1  ;
       DATA cAlias SIZE 55,9 FREEZELEFT { 1, 2 }

 DCBROWSECOL FIELD COLLECT->descrip ;
   HEADER "Description" PARENT oBrowse

 DCBROWSECOL FIELD COLLECT->type ;
   HEADER "Type" PARENT oBrowse

 DCBROWSECOL FIELD COLLECT->sub_type ;
   HEADER "SubType" PARENT oBrowse

 DCBROWSECOL FIELD COLLECT->location ;
   HEADER "Location" PARENT oBrowse

 DCBROWSECOL DATA {|a|a:={'Yes','No','Not Sure'},a[COLLECT->for_sale+1]} ;
   HEADER "For Sale?" PARENT oBrowse

 DCBROWSECOL FIELD COLLECT->date_orig ;
   HEADER "Orig Date" PARENT oBrowse

 DCBROWSECOL FIELD COLLECT->date_acqu ;
   HEADER "Acqu Date" PARENT oBrowse

 DCBROWSECOL FIELD COLLECT->orig_price ;
   HEADER "Acqu Price" PARENT oBrowse

 DCBROWSECOL FIELD COLLECT->appr_value ;
   HEADER "Appr Value" PARENT oBrowse

 DCBROWSECOL FIELD COLLECT->condition ;
   HEADER "Condition" PARENT oBrowse

 DCBROWSECOL DATA {||IIF(COLLECT->original,'Yes','No')} ;
   HEADER "Orig Owner?" PARENT oBrowse

 /* ---- Tab Page #2 ---- */

 @  0,0 DCTABPAGE oTabPage2 CAPTION 'Directory' ;
    RELATIVE oTabPage1

 aDirectory := Directory()

 @ 2,2 DCBROWSE oDirectory PARENT oTabPage2 ;
       DATA aDirectory SIZE 55,9

 DCBROWSECOL ELEMENT 1 HEADER "Name" PARENT oDirectory WIDTH 10

 DCBROWSECOL ELEMENT 2 HEADER "Size" PARENT oDirectory WIDTH 8

 DCBROWSECOL ELEMENT 3 HEADER "Date" PARENT oDirectory WIDTH 8

 DCBROWSECOL ELEMENT 4 HEADER "Time" PARENT oDirectory WIDTH 8

 DCREAD GUI ;
   TITLE "My COLLECTION" ;
   FIT ;
   ADDBUTTONS ;
   EVAL {||oBrowse:hide(), oBrowse:show()}

 RETURN

 /*
 This example demonstrates an array browse with source
 written to HTML.
 */

FUNCTION XTest2()

LOCAL i, j, GetList[0], cHtml, oBrowse, aDir := Directory()

@ 0,0 DCBROWSE oBrowse SIZE 4,10 DATA aDir

DCBROWSECOL ELEMENT 1 HEADER 'File Name' PARENT oBrowse
DCBROWSECOL ELEMENT 2 HEADER 'File Size' PARENT oBrowse
DCBROWSECOL ELEMENT 3 HEADER 'File Date' PARENT oBrowse
DCBROWSECOL ELEMENT 4 HEADER 'File Time' PARENT oBrowse

DCREAD HTML TO cHtml
MemoWrit('TEST.HTM',cHtml)

RETURN nil

Files:

DCDIALOG.CH

See Also:

   @ DCBROWSE (2)
   DCBROWSECOL
   dc_getbrowarray()
   dc_browserow()


@ DCBROWSE (2)

Create a BROWSE object for displaying with GUI reader

<< continued from @ DCBROWSE >> <br><br> The command @..DCBROWSE creates a new Browse definition and adds it to the array named GETLIST which is later processed by the DC_Read*() functions or by the DCREAD * commands. The GETLIST array must be first declared and initialized to the value of {}. <br><br> The command DCREAD GUI creates the DC_Xbp*() objects and activates the edit mode for all definitions found in the GetList array.<br><br> The command DCREAD HTML creates the DC_Html*() objects and writes the HTML source code.<br><br> A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> A DCBROWSE object is a parent to DCBROWSECOL objects (the columns of the browse). DCBROWSE is used to browse either arrays or databases.<br><br> @..DCBROWSE objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCCHECKBOX, @..DCRADIO, @..DCBUTTON, @..DCTABPAGE, @..DCTABLE or @..DCHTML*.<br><br>

Syntax:

  << continued from @ DCBROWSE >>

    [SORTSCOLOR <anSortedColorFG> [,<anSortedColorBG>] ];
    [SORTUCOLOR <anUnSortedColorFG> [,<anUnSortedColorBG>] ] ;
    [SORTNONCOLOR <anNonSortedColorFG> [,<anNonSortedColorBG>] ];
    [DESCENDING] ;
    [NODESCENDTOGGLE] ;
    [NORESTORE] ;
    [FILTER <bFilter>] ;
    [RESIZE <aResize> [SCALEFONT] ] ;
    [RESIZECOLUMNS] ;
    [DRAG <bDrag> [DIALOG <bDD>] ;
    [DROP <bDrop> [CURSOR <nDropCursor>] ;
    [TAGENABLE] ;
       [TAGELEMENT <nTagElement>] ;
       [TAGCOLOR <nTagColorFG>, <nTagColorBG>] ;
       [TAGMODE <nTagMode>] ;
    [SUBCLASS <cSubClass>] ;
    [USEVISUALSTYLE] ;
    [SCROLLBARTOOLTIP <bScrollBarTooltip>] ;
    [OWNERDRAW <bOwnerDraw>] ;
    [SCROLLBARHEIGHT <nScrollBarHeight>] ;
    [NAVMODE <nNavMode>] ;
    [RECORDOBJECT <oRecord>]

Arguments:

SORTSCOLOR <anSortedColorFG> [,<anSortedColorBG>] is used to set
the color of the column heading that is chosen as the controlling
sort order when click the mouse in the column heading.  See the
SORT clause of DCBROWSECOL.

SORTUCOLOR <anUnSortedColorFG> [,<anUnSortedColorBG>] is used to
set the color of the column headings that are not the controlling
sort order.

SORTNONCOLOR <anNonSortedColorFG> [,<anNonSortedColorBG>] is used to
set the color of the column headings that are not sortable columns.

DESCENDING is used to set the controlling sort order to descending.

NODESCENDTOGGLE is used to disable the toggling of the sort
order from ascending to descending on each successive click in
the heading column when using the SORT clause of DCBROWSECOL.

NOTE: The function DC_BrowseSort() is used to set the defaults
      for the SORT* clauses.

NORESTORE will ignore the setting of DC_AutoRestoreBrowse() and
will not save/restore browses to the registry.

FILTER <bFilter> is used when browsing arrays only.  The <bFilter>
code block is passed a pointer to the current array row.  The
code block must return a logical .TRUE. to include the element
in the browse, .FALSE. otherwise.

  Example: @ .. DCBROWSE .. FILTER {|a|'.DBF'$Upper(a[1])}

RESIZE <aResize> is an optional array of two (2) elements
used for resizing and repositioning the object when the parent
is resized.

NOTE: RESIZE is to be used in conjunction with the RESIZE clause
      of DCGETOPTIONS. See the RESIZE clause of DCGETOPTIONS for
      examples.

      The optional SCALEFONT clause will automatically scale the
      font size up or down when the object is resized.

RESIZECOLUMNS causes columns to be resized proportionally as the
browse width is resized.

DRAG <bDrag> is a codeblock to evaluate when the left mouse button
is clicked in the object and the drag is started.  The return
value of the code block will be stored in memory to be later
retrieved by the Drop operation. A pointer to the clicked on
object is passed to the code block.

DIALOG <bDD> is a codeblock that will evaluate when the drag is
started.  This is used to call a function that will create a
dialog window which will move with the mouse during the drag.
The dialog window will be destroyed upon the drop operation
or the release of the mouse.

Ex: DRAG {|o|o:getData()} DIALOG {|mp1,mp2,oXbp|DragDialog(mp1,mp2,oXbp)} ;

DROP <bDrop> is a codeblock to evaluate when the left mouse button
is released in the object and the drag is ended.  A pointer to
the object and the value stored in memory at the start of the
Drag are passed to the code block.

CURSOR <nDropCursor> is the mouse cursor that will show when it
is moved over this object during a drag operation.

Ex: DROP {|o,x|o:setData(x),o:invalidateRect()} ;
       CURSOR CURSOR POINTER_DATADROP_ASSIGN

TAGENABLE enables tag mode.  This allows rows to be tagged or
untagged by using the Left Mouse and the Ctrl or Shift key,
similar to Windows Explorer.  When browsing an array, the tag
is applied as a .TRUE. to a sub-element of the browse.  The
logical element that holds the tag should be initialized to .FALSE.
for all rows.  This element is defined by the TAGLEMENT <nTagElement>
clause.  When browsing a database, the tag is applied by using
the DC_RecTagToggle() function, thereby adding the record number
or removing the record number from an array named DC_RecTagArray().
TAGCOLOR <nTagColorFG>, <nTagColorBG> are foreground and background
colors to apply to rows of the browse that have been tagged.
TAGMODE <nTagMode> determines the behavior when the mouse has
been clicked in a row and neither the Ctrl or the Shift key are
pressed.  If <nTagMode> is DCGUI_TAGMODE_CLEAR, then all tags
of all rows will be cleared.  If <nTagMode> is DCGUI_TAGMODE_SET,
then all tags of all rows will first be cleared, then the tag of
the clicked-on row will be set.  See .\SAMPLES\TAGGING for an
example.  TAGELEMENT may also be a character string when browsing
an array of objects.  This would be the name of a logical iVar.

SUBCLASS <cSubClass> is a string containing a class name that
will be used to create the class, rather than DC_XbpBrowse().
This class should inherit from DC_XbpBrowse().
See the example in \exp19\samples\subclass.

USEVISUALSTYLE will enable Visual Styles selected by the Windows
operating system.

SCROLLBARTOOLTIP <bScrollBarToolTip> is a code block to evaluate
when the mouse is moved over the vertical scrollbar.
Example:

SCROLLBARTOOLTIP ;
{||'This is record ' + Alltrim(Str(COLLECT->(DC_KeyNo()))) + ;
   ';of ' + Alltrim(Str(COLLECT->(DC_KeyCount()))) + ' total records'}

OWNERDRAW <bOwnerDraw> is a code block to evaluate when the browse
cells are drawn by the owner rather than the default method.  Two
parameters are passed to <bOwnerDraw>: oPS and aInfo. OWNERDRAW
provides the ownerdraw capability to the browse system.  See the
example in .\samples\browse\ownerdraw.prg.

SCROLLBARHEIGHT <nScrollBarHeight> set the width and height of the
browse scrollbars in pixels.  The default is 17.

NAVMODE <nNavMode> is an option that controls the way the browse
handles navigation.  The default is XBPBRW_NAVIGATION_1XCOMPATIBLE.
The other option is XBPBRW_NAVIGATION_SYSTEM. This option is
available only in Xbase++ 2.0 or later. See the Alaska documentation
for XbpBrowse:navigationMode.

RECORDOBJECT <oRecord> is an optional record object created by
DC_DbRecord():new().  The is used in conjunction with DCBROWSECOL
DATA codeblocks that contain pointers to the record iVars.  The
navigation code blocks of the browse force a oRecord:scatter() of
the record into the object before each row is painted.  See the
sample program .\samples\dbrecord\browse.prg (Tab 3).

Files:

DCDIALOG.CH

See Also:

   DCBROWSECOL
   dc_getbrowarray()
   dc_browserow()
   dc_browsecolor()


@ DCCHECKBOX

Create a CHECKBOX object for displaying with GUI reader

The command @..DCCHECKBOX creates a new Check Box definition and it to the array named GETLIST which is later processed by the DC_Read*() functions or by the DCREAD * commands. The GETLIST array must be first declared and initialized to the value of {}. <br><br> The command DCREAD GUI creates the DC_Xbp*() objects and activates the edit mode for all definitions found in the GetList array. <br><br> The command DCREAD HTML creates the DC_Html*() objects and writes the HTML source code.<br><br> A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all objects referenced by the GetList array to be released. <br><br> @..DCCHECKBOX objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCRADIO, @..DCTABLE, @..DCPUSHBUTTON or @..DCTABPAGE.<br><br>

Syntax:

@ <nGetRow>,<nGetCol> DCCHECKBOX <uVar> ;
  [DELIMVAR <cDelim>] ;
  [PROMPT <bcPrompt>] ;
  [PARENT <oParent>] ;
  [PARENTID <cParentId>] ;
  [DATALINK <bLink>] ;
  [MESSAGE <bcMsg> [INTO <oMsgBox>]] ;
  [COLOR <bncFgC> [,<ncBgC>] ] ;
  [CARGO <xCargo>] ;
  [WHEN <bWhen>] ;
  [HIDE <bHide>] ;
  [EDITPROTECT <bProtect>] ;
  [FONT <bocFont>] ;
  [SIZE <nWidth>,<nHeight>] ;
  [PRESENTATION <aPres>] ;
  [PIXEL] ;
  [TOOLTIP <bcToolTip>] ;
  [OBJECT <oObject>] ;
  [CURSOR <naCursor>] ;
  [PREEVAL <bPreEval>] ;
  [EVAL <bEval,...>] ;
  [RELATIVE <oRel>] ;
  [ID <cId>] ;
  [TITLE <cTitle>] ;
  [ACCELKEY <anAccel>] ;
  [GOTFOCUS <bGotFocus>] ;
  [LOSTFOCUS <bLostFocus>] ;
  [TABSTOP] ;
  [NOTABSTOP] ;
  [TABGROUP <nTabGroup>] ;
  [VISIBLE] ;
  [INVISIBLE] ;
  [GROUP <cGroup>] ;
  [ACTION <bAction>] ;
  [RESIZE <bResize> [SCALEFONT] ] ;
  [OPTIONS <nOptions>] ;
  [DRAG <bDrag> [DIALOG <bDD>] ;
  [DROP <bDrop> [CURSOR <nDropCursor>] ;
  [SUBCLASS <cSubClass>]

Arguments:

GUI applications:

<nRow> and <nCol> are the row and column of the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE <oRel> argument is
used.  If no parent is assigned, then the parent is the Dialog
box. IF the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel
mode by including PIXEL as a command argument.

HTML applications:

<nRow> and <nCol> are the row number and column number of
the table if the parent of this object is a DCTABLE. The
text will be inserted in the cell of the table defined by
the row/column.

<lVar> is the variable to GET.  This must be a initialized to
a logical value. It must not be a macro. The <lVar> is
automatically anchored via a Get-Set codeblock created by
DC_GetAnchorCB() unless <lVar> is a custom Get-Set code block.
Macros may be used in a custom Get-Set code block.

OBJECT <oObject> is the variable to use as a container for the
object after it is created by the GUI reader.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

DELIMVAR <cDelim> is for text-based screens only and is
ignored when DC_GUI() is .TRUE.  This is a three character
sequence to use for the checkbox - the default is (*).

PROMPT <bcPrompt> is the prompt to display immediately to
the right of the checkbox.  It may be a character string or a
code block that returns a character string.

SIZE <nWidth>,<nHeight> is the width and height of the
prompt.  If the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based numbers.

MESSAGE <bcMsg> is the message you want to display in the
message area of the dialogue screen defined by the DCMESSAGEBOX
command when the object is in focus.  Optionally, INTO <oMsgBox>
will designate which message box to display the message into.
If the INTO clause is not used, then the last message box in the
GetList is the default. <oMsgBox> may also be any object that
supports the :setCaption() method.  If <bcMsg> is a code-block,
it must return a character string.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the object will be disabled and grayed.
If the value returned is .TRUE. then the object will be enabled.
The object is passed as a parameter to the code block.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.
The object is passed as a parameter to the code block.

EDITPROTECT <bProtect> is an optional condition tested during the
execution of the GUI gets by the DCREAD GUI command, before the
object receives input focus (before it is activated). When the
condition returns the value .T. (true), the object receives the
input focus.  Otherwise, it is skipped. <bProtect> is a code
block that must return a logical value when evaluated. The code
block is evaluated prior to the object receiving input focus.
This clause behaves similar to the WHEN clause with the exception
that the object is not disabled (grayed out).  The object is
passed as a parameter to the code block.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.   If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

DATALINK <bLink> is an optional code block that is evaluated
every time Get/Set codeblock is evaluated, ie when the data
is read from the <uVar> into the object except when using
a user-defined Get/Set code block. <bLink> is also
evaluated when DC_GetRefresh() is called unless the <lDataLink>
parameter of DC_GetRefresh() is .FALSE.

FONT <cFont> is a character string defining an optional font.
The font string must conform to the Xbase++ standard, ie.
"10.Courier Bold". It may also be a font object or a code block
that returns a character string or a font object to later
refresh with DC_GetRefresh().

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the CheckBox object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.

TOOLTIP <bcToolTip> is a character string which will display
as a "Tool Tip" next to the object when the cursor is passed
over the object. A semi-colon within the text indicates a new
line.  If <bcToolTip> is a code-block, it must return a character
string.  NOTE: The Tooltip painting method is run in another
thread, therefore the codeblock should not run code that points
to the current work area.  It may however, contain local, public
or private variables.

CURSOR <naCursor> may be either a numeric value or an array of
3 elements which defines an optional mouse pointer to use for
this object.  System mouse pointers start with
XBPWINDOW_POINTERTYPE_ and are defined in XPB.CH.  The default
pointer is XBPWINDOW_POINTERTYPE_POINTER.  <naCursor> may be a
numeric resource ID that points to a Bit-Map that has been
compiled with the resource compiler and linked to the .EXE.
<naCursor> may be a 3-element array described as follows:

   Element  Type  Description
   -------  ---- ---------------------------------------------
     [1]      C   Optional name of .DLL containing the pointer
                  resource.

     [2]      N   The numeric resource ID of the pointer.  If
                  element 1 is a NIL, then this resource must be
                  linked into the .EXE.

     [3]      N   The type of resource as defined in XBP.CH.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

COLOR <ncFGc>, <ncBGc> are foreground and background colors.
They may be character strings representing valid text-based
colors supported by SetColor() or they may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH. IF <bncFGc> is a
code block is must return a 2-element array containing a
foreground and background color.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

  [1] - A numeric value that is a pointer to the Getlist array
        for this object.

  [2] - A pointer to the GetList array.

  [3] - The value of <xCargo>.

  [4] and up - optional values added by the GUI reader.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

ACCELKEY <anAccel> is a numeric "hot-key" assignment that will set
focus to the checkbox object when the hot-key is pressed.  The key
must be a valid key with the prefix xbeK_*.  These keys are
defined in APPEVENT.CH.  <anAccel> may also be an array of numeric
values to assign more than one key to the object.

GOTFOCUS <bGotFocus> is a code block that is evaluated when this
object receives input focus. <bGotFocus> := {|uNIL1,uNIL2,self|...}

LOSTFOCUS <bLostFocus> is a code block that is evaluated when this
object loses input focus.  <bLostFocus> := {|uNIL1,uNIL2,self|...}

TABSTOP will cause the object (Xbase Part) to be set when using
the Tab key.  Note: When logical groups are defined in a dialog
using TABGROUP <nTabGroup>, TABSTOP is usually set to .T. (true)
for the first dialog element in the group.  This allows the first
dialog element of a group to be activated using the Tab key.

NOTABSTOP will cause the object (Xbase Part) to be ignored when
using the Tab key. This clause is needed only to override any
default setting of TabStop by the DCGETOPTIONS [TABSTOP] command.

TABGROUP <nTabGroup> allows objects (Xbase Parts) that are created
immediately after one another in the GetList to be combined into
logical groups. This allows the user to navigate within a dialog
from group to group by pressing the Tab key.  Within a group of
dialog elements navigation is performed using the cursor keys.

Only constants defined in the XBP.CH file can be used as values
for this instance variable.  The following table lists the
available constants:

 #define constants for <nTabGroup>:

  Constant             Description

  XBP_NO_GROUP     *)  Dialog element does not belong to a group
  XBP_BEGIN_GROUP      Dialog element is the first in a group
                       (this begins the definition of the group)
  XBP_WITHIN_GROUP     Dialog element is within a group
  XBP_END_GROUP        Dialog element is the last in a group
                       (this ends the definition of the group)

 *) Default value

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS

ACTION <bAction> is a code block to evaluate when the checkbox is
selected.

RESIZE <aResize> is an optional array of two (2) elements
used for resizing and repositioning the object when the parent
is resized.

NOTE: RESIZE is to be used in conjunction with the RESIZE clause
      of DCGETOPTIONS. See the RESIZE clause of DCGETOPTIONS for
      examples.

      The optional SCALEFONT clause will automatically scale the
      font size up or down when the object is resized.

OPTIONS <nOptions> is a set of options to use to determine the
visual properties of the Checkbox.  The options are numerical
definitions starting with BS_* and are defined in DCDIALOG.CH.

Note the most common option is BS_PUSHLIKE.

DRAG <bDrag> is a codeblock to evaluate when the left mouse button
is clicked in the object and the drag is started.  The return
value of the code block will be stored in memory to be later
retrieved by the Drop operation. A pointer to the clicked on
object is passed to the code block.

DIALOG <bDD> is a codeblock that will evaluate when the drag is
started.  This is used to call a function that will create a
dialog window which will move with the mouse during the drag.
The dialog window will be destroyed upon the drop operation
or the release of the mouse.

Ex: DRAG {|o|o:getData()} DIALOG {|mp1,mp2,oXbp|DragDialog(mp1,mp2,oXbp)} ;

DROP <bDrop> is a codeblock to evaluate when the left mouse button
is released in the object and the drag is ended.  A pointer to
the object and the value stored in memory at the start of the
Drag are passed to the code block.

CURSOR <nDropCursor> is the mouse cursor that will show when it
is moved over this object during a drag operation.

Ex: DROP {|o,x|o:setData(x),o:invalidateRect()} ;
       CURSOR CURSOR POINTER_DATADROP_ASSIGN

SUBCLASS <cSubClass> is a string containing a class name that
will be used to create the class, rather than DC_XbpCheckBox().
This class should inherit from DC_XbpCheckBox().
See the example in \exp19\samples\subclass.

Notes:

GUI Applications : The checkbox object created by @ DCCHECKBOX is an object of the DC_XbpCheckBox() class which inherits from the XbpCheckBox() class, therefore it can be manipulated with any iVar or method supported by XbpCheckBox().

--------------------

HTML Applications :

The checkbox object created by @ DCCHECKBOX is an object of the DC_HtmlCheckBox() class.

Examples:

/*  (Simple Check Boxes in GUI)  */

#include "dcdialog.ch"

PROCEDURE Xtest()

LOCAL lDict := .f., lSource := .t., lBackup := .f., ;
      lPack := .t.,  GetList := {}

@ 5,10 DCCHECKBOX lDict   PROMPT 'Save to Dictionary'
@ 5,40 DCCHECKBOX lSource PROMPT 'Save to Source Code'
@ 7,10 DCCHECKBOX lBackUp PROMPT 'Make a Backup file'
@ 7,40 DCCHECKBOX lPack   PROMPT 'Pack the File'

DCREAD GUI FIT ADDBUTTONS

RETURN

/* Simple Checkboxes in HTML */

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], oForm, cHtml, oTable, lCheck1, lCheck2, lCheck3

DCFORM OBJECT oForm
DCTABLE OBJECT oTable PARENT oForm ROWS 3 COLUMNS 1
lCheck1 := .t.
lCheck2 := .f.
lCheck3 := .f.
@ 1,1 DCCHECKBOX lCheck1 PROMPT 'Check me first' PARENT oTable
@ 2,1 DCCHECKBOX lCheck2 PROMPT 'Check me second' PARENT oTable
@ 3,1 DCCHECKBOX lCheck3 PROMPT 'Check me third' PARENT oTable

DCREAD HTML TO cHtml

MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

DCDIALOG.CH                                                     I

See Also:

   dc_htmlcheckbox()
   dc_readgui()
   dc_readhtml()
   DCREAD GUI
   DCREAD HTML


@ DCCOMBOBOX

Create a COMBOBOX object for displaying with GUI reader

The command @..DCCOMBOBOX creates a new Combo Box definition and adds it to the array named GETLIST which is later processed by the DC_Read*() functions or by the DCREAD * commands. The GETLIST array must be first declared and initialized to the value of {}. <br><br> The command DCREAD GUI creates the DC_Xbp*() objects and activates the edit mode for all definitions found in the GetList array. <br><br> The command DCREAD HTML creates the DC_Html*() objects and writes the HTML source code.<br><br> A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> @..DCCOMBOBOX objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCRADIO, @..DCPUSHBUTTON, @..DCCHECKBOX or @..DCTABPAGE.<br><br>

Syntax:

@ <nRow>,<nCol> DCCOMBOBOX <uOutVar> LIST <aVar> ;
    [TYPE <nType>] ;
    [SIZE <nGetWidth> [,<nGetHeight>]] ;
    [PIXEL] ;
    [REFRESH] ;
    [IMMEDIATE] ;
    [ITEMMARKED <bItemMarked>] ;
    [ITEMSELECTED <bItemSelected>] ;
    [PARENT <oParent>] ;
    [PARENTID <cParentId>] ;
    [FONT <bocFont>] ;
    [MESSAGE <bcMsg> [INTO <oMsgBox>]] ;
    [WHEN <bWhen>] ;
    [HIDE <bHide>] ;
    [EDITPROTECT <bProtect>] ;
    [VALID <bValid>] ;
    [HELPCODE <cHelp>] ;
    [PRESENTATION <aPres>] ;
    [TOOLTIP <bcToolTip>] ;
    [CURSOR <naCursor>] ;
    [PREEVAL <bPreEval>] ;
    [EVAL <bEval>] ;
    [DATALINK <bLink>] ;
    [OBJECT <oObject>] ;
    [RELATIVE <oRel>] ;
    [CARGO <xCargo>] ;
    [COLOR <bncFgC> [,<ncBgC>] ] ;
    [ID <cId>] ;
    [TITLE <cTitle>] ;
    [ACCELKEY <anAccel>] ;
    [GOTFOCUS <bGotFocus>] ;
    [LOSTFOCUS <bLostFocus>] ;
    [TABSTOP] ;
    [NOTABSTOP] ;
    [TABGROUP <nTabGroup>] ;
    [VISIBLE] ;
    [INVISIBLE] ;
    [GROUP <cGroup> ;
    [RESIZE <bResize> [SCALEFONT] ] ;
    [DRAG <bDrag> [DIALOG <bDD>] ;
    [DROP <bDrop> [CURSOR <nDropCursor>] ;
    [SUBCLASS <cSubClass>]

Arguments:

GUI applications:

<nRow> and <nCol> are the row and column of the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE argument is used.
If no parent is assigned, then the parent is the Dialog box.
IF the PIXEL option is set to .TRUE. in DCGETOPTIONS, then
the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel
mode by including PIXEL as a command argument.

HTML applications:

<nRow> and <nCol> are the row number and column number of
the table if the parent of this object is a DCTABLE. The
text will be inserted in the cell of the table defined by
the row/column.

<aVar> is a single-dimensional array of character strings
which is used as the list box of items.

<cOutVar> is the input/output variable.  This should be
initialized to a character string. It must not be a macro,
however it may be a code block that contains a macro. The <uVar>
is automatically anchored via a Get-Set codeblock created by
DC_GetAnchorCB() unless <uVar> is a custom Get-Set code block.

TYPE <nType> is a numeric constant which is defined in the XBP.CH
file and are listed in the following table:

  Constant                Description

  XBPCOMBO_SIMPLE         List box is always dropped down
  XBPCOMBO_DROPDOWN   *)  List box dropped down via a mouse click
  XBPCOMBO_DROPDOWNLIST   List box dropped down via a mouse click
                          and keyboard input in the entry field is
                          not allowed

  *) Default value

SIZE <nWidth>,<nHeight> is the width and height of the
combobox.  If the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based numbers.  Note:  The height value  determines the total
height of the combo box including the pull-down listbox.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.  If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

REFRESH will force a refresh of the GetList each time an item is
chosen from the pick-list.  Use this clause if other objects in
the GetList contain a WHEN or HIDE clause which is dependent on
the value picked.

IMMEDIATE will cause the data in the list box to be set into the
variable immediately when the item in the list box is marked,
otherwise the data will be set when the item is selected.

ITEMMARKED <bItemMarked> is a code block to evaluate each time an
item in the listbox is marked by moving the mouse over the item.

ITEMSELECTED <bItemSelected> is a code block to evaluate when the
mouse is clicked on an item in the listbox or the ENTER key is
pressed.

OBJECT <oObject> is the variable to use as a container for the
object after it is created by the GUI reader.

FONT <cFont> is a character string defining an optional font.
The font string must conform to the Xbase++ standard, ie.
"10.Courier Bold". It may also be a font object or a code block
that returns a character string or a font object to later
refresh with DC_GetRefresh().

MESSAGE <bcMsg> is the message you want to display in the
message area of the dialogue screen defined by the DCMESSAGEBOX
command when the object is in focus.  Optionally, INTO <oMsgBox>
will designate which message box to display the message into.
If the INTO clause is not used, then the last message box in the
GetList is the default.  <oMsgBox> may also be any object that
supports the :setCaption() method.  <bcMsg> may be a code block
that returns a character value.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the object will be disabled and grayed.
If the value returned is .TRUE. then the object will be enabled.
The object is passed as a parameter to the code block.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.
the object is passed as a parameter to the code block.

EDITPROTECT <bProtect> is an optional condition tested during the
execution of the GUI gets by the DCREAD GUI command, before the
object receives input focus (before it is activated). When the
condition returns the value .T. (true), the object receives the
input focus.  Otherwise, it is skipped. <bProtect> is a code
block that must return a logical value when evaluated. The code
block is evaluated prior to the object receiving input focus.
This clause behaves similar to the WHEN clause with the exception
that the object is not disabled (grayed out).  The object is
passed as a parameter to the code block.

VALID <bValid> is an optional condition tested during the
execution of the GUI gets by the READ command before a Get
object loses input focus (before it is deactivated).  When
the condition returns the value .T. (true), the Get object
loses the input focus.  Otherwise, it remains active. <bValid>
is a code block that must return a logical value when it is
evaluated.  The object passed as a parameter to the code block.

HELPCODE <cHelp> is a character string that is passed to the
DC_HelpF1() function if F1 is pressed or the HELP button
is clicked when this GET has focus.  This HELPCODE allows
the Help system to override the passing of the Procedure and
Varname for more specific context-help.

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the ComboBox object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.

TOOLTIP <bcToolTip> is a character string which will display
as a "Tool Tip" next to the object when the cursor is passed
over the object. A semi-colon within the text indicates a new
line.  If <bcToolTip> is a code-block, it must return a character
string.  NOTE: The Tooltip painting method is run in another
thread, therefore the codeblock should not run code that points
to the current work area.  It may however, contain local, public
or private variables.

CURSOR <naCursor> may be either a numeric value or an array of
3 elements which defines an optional mouse pointer to use for
this object.  System mouse pointers start with
XBPWINDOW_POINTERTYPE_ and are defined in XPB.CH.  The default
pointer is XBPWINDOW_POINTERTYPE_POINTER.  <naCursor> may be a
numeric resource ID that points to a Bit-Map that has been
compiled with the resource compiler and linked to the .EXE.
<naCursor> may be a 3-element array described as follows:

   Element  Type  Description
   -------  ---- ---------------------------------------------
     [1]      C   Optional name of .DLL containing the pointer
                  resource.

     [2]      N   The numeric resource ID of the pointer.  If
                  element 1 is a NIL, then this resource must be
                  linked into the .EXE.

     [3]      N   The type of resource as defined in XBP.CH.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

DATALINK <bLink> is an optional code block that is evaluated
every time Get/Set codeblock is evaluated, ie when the data
is read from the <uVar> into the object except when using
a user-defined Get/Set code block. <bLink> is also
evaluated when DC_GetRefresh() is called unless the <lDataLink>
parameter of DC_GetRefresh() is .FALSE.

 NOTE: Due to anomolies in the event model of the XbpComboBox
       class, <bLink> may be evaluated erratically, therefore it
       it recommended that the ITEMSELECTED or ITEMMARKED clause
       be used.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

  [1] - A numeric value that is a pointer to the Getlist array
        for this object.

  [2] - A pointer to the GetList array.

  [3] - The value of <xCargo>.

  [4] and up - optional values added by the GUI reader.

COLOR <ncFGc>, <ncBGc> are foreground and background colors.
They may be character strings representing valid text-based
colors supported by SetColor() or they may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH.  IF <bncFGc> is a
code block is must return a 2-element array containing a
foreground and background color.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

ACCELKEY <anAccel> is a numeric "hot-key" assignment that will set
focus to the checkbox object when the hot-key is pressed.  The key
must be a valid key with the prefix xbeK_*.  These keys are
defined in APPEVENT.CH.  <anAccel> may also be an array of numeric
values to assign more than one key to the object.

GOTFOCUS <bGotFocus> is a code block that is evaluated when this
object receives input focus.  <bGotFocus> := {|uNIL1,uNIL2,self|...}

LOSTFOCUS <bLostFocus> is a code block that is evaluated when this
object loses input focus.  <bLostFocus> := {|uNIL1,uNIL2,self|...}

TABSTOP will cause the object (Xbase Part) to be set when using
the Tab key.  Note: When logical groups are defined in a dialog
using TABGROUP <nTabGroup>, TABSTOP is usually set to .T. (true)
for the first dialog element in the group.  This allows the first
dialog element of a group to be activated using the Tab key.

NOTABSTOP will cause the object (Xbase Part) to be ignored when
using the Tab key. This clause is needed only to override any
default setting of TabStop by the DCGETOPTIONS [TABSTOP] command.

TABGROUP <nTabGroup> allows objects (Xbase Parts) that are created
immediately after one another in the GetList to be combined into
logical groups. This allows the user to navigate within a dialog
from group to group by pressing the Tab key.  Within a group of
dialog elements navigation is performed using the cursor keys.

Only constants defined in the XBP.CH file can be used as values
for this instance variable.  The following table lists the
available constants:

 #define constants for <nTabGroup>:

  Constant             Description

  XBP_NO_GROUP     *)  Dialog element does not belong to a group
  XBP_BEGIN_GROUP      Dialog element is the first in a group
                       (this begins the definition of the group)
  XBP_WITHIN_GROUP     Dialog element is within a group
  XBP_END_GROUP        Dialog element is the last in a group
                       (this ends the definition of the group)

 *) Default value

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS

RESIZE <aResize> is an optional array of two (2) elements
used for resizing and repositioning the object when the parent
is resized.

NOTE: RESIZE is to be used in conjunction with the RESIZE clause
      of DCGETOPTIONS. See the RESIZE clause of DCGETOPTIONS for
      examples.

      The optional SCALEFONT clause will automatically scale the
      font size up or down when the object is resized.

DRAG <bDrag> is a codeblock to evaluate when the left mouse button
is clicked in the object and the drag is started.  The return
value of the code block will be stored in memory to be later
retrieved by the Drop operation. A pointer to the clicked on
object is passed to the code block.

DIALOG <bDD> is a codeblock that will evaluate when the drag is
started.  This is used to call a function that will create a
dialog window which will move with the mouse during the drag.
The dialog window will be destroyed upon the drop operation
or the release of the mouse.

Ex: DRAG {|o|o:getData()} DIALOG {|mp1,mp2,oXbp|DragDialog(mp1,mp2,oXbp)} ;

DROP <bDrop> is a codeblock to evaluate when the left mouse button
is released in the object and the drag is ended.  A pointer to
the object and the value stored in memory at the start of the
Drag are passed to the code block.

CURSOR <nDropCursor> is the mouse cursor that will show when it
is moved over this object during a drag operation.

Ex: DROP {|o,x|o:setData(x),o:invalidateRect()} ;
       CURSOR CURSOR POINTER_DATADROP_ASSIGN

SUBCLASS <cSubClass> is a string containing a class name that
will be used to create the class, rather than DC_XbpComboBox().
This class should inherit from DC_XbpComboBox().
See the example in \exp19\samples\subclass.

Notes:

GUI Appications :

The combobox object created by @ DCCOMBOBOX is an object of the DC_XbpComboBox() class which inhertis from XbpComboBox(), therefore it can be manipulated with any iVar or method supported by XbpComboBox().

-----------------------------------

HTML Applications :

The combobox object created by @ DCCOMBOBOX is an object of the DC_HtmlComboBox() class.

Examples:

-- Example 1 (GUI combobox) ---

#include "dcdialog.ch"

PROCEDURE Xtest()

LOCAL aFields, Getlist := {}, cField

USE Customer
aFields := Array(FCount())
AFields( aFields ) // fill array with field list.
cField := Space(10)

@ 5,10 DCCOMBOBOX cField LIST aFields FONT "10.Courier"  ;
    SIZE 15,20

DCREAD GUI FIT ADDBUTTONS

RETURN

-- Example 2 (HTML checkboxes) --

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL GetList[0], oForm, cHtml, oTable, aList1, ;
      aList2, cVar1, cVar2

DCFORM OBJECT oForm
DCTABLE OBJECT oTable PARENT oForm ROWS 2 COLUMNS 1
cVar1 := Space(10)
cVar2 := Space(12)
aList1 := { 'Men','Women','Dogs','Cats','Mice','Geese','Turkeys' }
aList2 := { 'Democrat','Republican','HandyMan','Doctor','Plumber','Programmer' }

@ 1,1 DCSAY 'Pick a group' PARENT oTable
@ 1,1 DCCOMBOBOX cVar1 LIST aList1 PARENT oTable
@ 2,1 DCSAY 'Pick a profession' PARENT oTable
@ 2,1 DCCOMBOBOX cVar2 LIST aList2 PARENT oTable

DCREAD HTML TO cHtml

MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

DCDIALOG.CH

See Also:

   @ DCLISTBOX
   dc_vartolistbox()
   dc_readgui()
   dc_readhtml()
   dc_htmlcombobox()


@ DCCUSTOM

Create a CUSTOM object for displaying with GUI reader

The command DCCUSTOM is used to create a reference to a custom object and adds it to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> DCCUSTOM is used add a reference to a "custom" object. This command is used when there is a requirement to use a custom class or to manipulate an Xbase Parts class in a manner that is not currently supported by the DCDIALOG system. The DCCUSTOM command allows the programmer to combine any type of dialog object with stand DC* objects using a common dialog management system. Think of DCCUSTOM as an "extend" system for the eXPress++ dialog system.

Syntax:

@ <nRow>,<nCol> DCCUSTOM <bCustom> ;
    [SIZE <nWidth> [,<nHeight>]] ;
    [VAR <uVar>] ;
    [PARENT <oParent>] ;
    [PARENTID <cParentId>] ;
    [CAPTION <cCaption>] ;
    [PRESENTATION <aPres>] ;
    [TYPE <nType>] ;
    [OBJECT <oCustom>] ;
    [COLOR <bncFgC> [,<ncBgC>] ] ;
    [OPTIONS <aOptions>] ;
    [DATALINK <bLink>] ;
    [FONT <bocFont>] ;
    [MESSAGE <bcMsg> [INTO <oMsgBox>]] ;
    [HIDE <bHide>] ;
    [WHEN <bWhen>] ;
    [EDITPROTECT <bProtect>] ;
    [VALID <bValid>] ;
    [HELPCODE <cHelpCode>] ;
    [TOOLTIP <bcToolTip>] ;
    [ACTION <bAction>] ;
    [CURSOR <naCursor>] ;
    [CARGO <xCargo>] ;
    [PREEVAL <bPreEval>] ;
    [EVAL <bEval] ;
    [PIXEL] ;
    [RELATIVE <oRel>] ;
    [ID <cId>] ;
    [TITLE <cTitle>] ;
    [ACCELKEY <anAccel>] ;
    [GOTFOCUS <bGotFocus>] ;
    [LOSTFOCUS <bLostFocus>] ;
    [TABSTOP] ;
    [NOTABSTOP] ;
    [TABGROUP <nTabGroup>] ;
    [VISIBLE] ;
    [INVISIBLE] ;
    [GROUP <cGroup>] ;
    [RESIZE <aResize>] ;
    [DRAG <bDrag> [DIALOG <bDD>] ;
    [DROP <bDrop> [CURSOR <nDropCursor>]

Arguments:

<nRow>, <nCol> are the coordinates on the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE <oRel> argument is
used.  If no parent is assigned, then the parent is the Dialog
box.  IF the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel mode by
including PIXEL as a command argument.
<nRow> is stored in element nGETLIST_STARTROW.
<nCol> is stored in element nGETLIST_STARTCOL.

<bCustom> is a required code block.  This is the code block
that is evaluated to create the custom object.  It requires
the following form:

  { | <a> | <MyFunc>( <a> ) }

  <a> is an array of information that is passed to the custom
  function.

  Element  Type Description
  -------  ---- ------------------------------------------------

    [1]     A   The GetList array

    [2]     N   The GetList pointer (the element containing this
                object).

    [3]     O   The Parent object

    [4]     A   A two element array containing the start column
                and start row.  The values will be converted to
                pixel coordinates.

    [5]     A   A two element array containing the width and
                height of the object.  The values will be
                converted to pixels.

    [6]     A   Optional Presentation Parameters

    [7]     L   A .TRUE. if the object is VISIBLE.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

SIZE <nWidth>, <nHeight> defines the size of the object.
IF the PIXEL option is set to .TRUE. in DCGETOPTIONS, then
the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel mode by
including PIXEL in the command.
<nWidth> is stored in element nGETLIST_WIDTH
<nHeight> is stored in element nGETLIST_HEIGHT

VAR <uVar> is an optional memory variable that is used with
this object.  It is converted to a code block using the
function DC_GetAnchorCB() and stored in element bGETLIST_VAR.
This code block is usually attached to the :dataLink instance
var of an Xbase Parts object.  If <uVar> is a code block, then
it will not be converted by DC_GetAnchorCB().  In this case, it
must be a valid Get-Set code block.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.  If this
clause is not used, then the object will be displayed in the
top-level dialogue screen or in the object set with the
DCSETPARENT command. This is converted to a code-block by
the function DC_GetAnchorCB() and is stored in element
oGETLIST_PARENT.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

<oGroup> is the name of the variable to assign as a storage
place for this object.  It is converted to a code-block by
the function DC_GetAnchorCB() and is stored in element
oGETLIST_GROUP.

CAPTION <cCaption> is the caption to use with the object
and is stored in element cGETLIST_CAPTION.

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.  The array is stored in element
aGETLIST_PRESENTATION.

TYPE <nType> defines the "type" of the object and is stored
in element nGETLIST_TYPE.

OBJECT <oObject> is a local variable to store a reference to
this object.  It is converted to a code-block by the function
DC_GetAnchorCB() and is stored in element oGETLIST_OBJECT.

COLOR <cColor> is a text-based color string for the object
that is stored in element cGETLIST_COLOR.

OPTIONS <xOptions> can be any type of variable.  It is stored
in element xGETLIST_OPTIONS.

DATALINK is an optional code block that is attached to the
<uVar> via the function DC_GetAnchorCB().  This code block is
evaluated when the :dataLink var is evaluated by an Xbase
Parts object.

FONT <cFont> is a font to use with this object and is stored
in element cGETLIST_FONT. It may be a character string, a font
object or a code block that returns a character string or a font
object to later refresh with DC_GetRefresh().

MESSAGE <cMsg> is the message you want to display in the
message area of the dialogue screen defined by the DCMESSAGEBOX
command when the object is in focus.  Optionally, INTO <oMsgBox>
will designate which message box to display the message into.
If the INTO clause is not used, then the last message box in the
GetList is the default. <oMsgBox> may also be any object that
supports the :setCaption() method.  If <bcMsg> is a code-block,
it must return a character string.

PICTURE <cPict> is a character string specifying formatting
options for the value of <uVar> during display and editing.
It is stored in element cGETLIST_PICTURE.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the object will be disabled and grayed.
If the value returned is .TRUE. then the object will be enabled.
The code block is stored in element bGETLIST_WHEN.
The object is passed as a parameter to the code block.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.
The object is passed as a parameter to the code block.

EDITPROTECT <bProtect> is an optional condition tested during the
execution of the GUI gets by the DCREAD GUI command, before the
object receives input focus (before it is activated). When the
condition returns the value .T. (true), the object receives the
input focus.  Otherwise, it is skipped. <bProtect> is a code
block that must return a logical value when evaluated. The code
block is evaluated prior to the object receiving input focus.
This clause behaves similar to the WHEN clause with the exception
that the object is not disabled (grayed out).  The object is
passed as a parameter to the code block.

VALID <bValid> is an optional condition tested during the
navigation through the dialog objects when an object loses
focus (before it is deactivated).  If the condition returns the
value .T. (true), the object loses the input focus, otherwise,
it remains active. <bValid> is a code block that must return a
logical value when it is evaluated.  The object is passed to the
code block prior to the object losing input focus.  The
code block is stored in element bGETLIST_VALID.

HELPCODE <cHelp> is a character string that is passed to the
DC_HelpF1() function if F1 is pressed or the HELP button
is clicked when this object has focus.  This HELPCODE allows
the Help system to override the passing of the Procedure and
Varname for more specific context-help.  The help code is
stored in element cGETLIST_HELPCODE.

TOOLTIP <bcToolTip> is a character string which will display
as a "Tool Tip" next to the object when the cursor is passed
over the object. A semi-colon within the text indicates a new
line.  If <bcToolTip> is a code-block, it must return a character
string.  NOTE: The Tooltip painting method is run in another
thread, therefore the codeblock should not run code that points
to the current work area.  It may however, contain local, public
or private variables.

CURSOR <naCursor> may be either a numeric value or an array of
3 elements which defines an optional mouse pointer to use for
this object.  System mouse pointers start with
XBPWINDOW_POINTERTYPE_ and are defined in XPB.CH.  The default
pointer is XBPWINDOW_POINTERTYPE_POINTER.  <naCursor> may be a
numeric resource ID that points to a Bit-Map that has been
compiled with the resource compiler and linked to the .EXE.
<naCursor> may be a 3-element array described as follows:

  Element  Type  Description
  -------  ---- ---------------------------------------------
    [1]      C   Optional name of .DLL containing the pointer
                 resource.

    [2]      N   The numeric resource ID of the pointer.  If
                 element 1 is a NIL, then this resource must be
                 linked into the .EXE.

    [3]      N   The type of resource as defined in XBP.CH.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

<xCargo> is stored in element xGETLIST_CARGO.

ACTION <bAction> is a code-block to be used with objects
that execute an action, like push-buttons.  This code block
is stored in element bGETLIST_ACTION.

COLOR <ncFGc>, <ncBGc> are foreground and background colors.
They may be character strings representing valid text-based
colors supported by SetColor() or they may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

ACCELKEY <anAccel> is a numeric "hot-key" assignment that will set
focus to the checkbox object when the hot-key is pressed.  The key
must be a valid key with the prefix xbeK_*.  These keys are
defined in APPEVENT.CH.  <anAccel> may also be an array of numeric
values to assign more than one key to the object.

GOTFOCUS <bGotFocus> is a code block that is evaluated when this
object receives input focus.  <bGotFocus> := {|uNIL1,uNIL2,self|...}

LOSTFOCUS <bLostFocus> is a code block that is evaluated when this
object loses input focus.  <bLostFocus> := {|uNIL1,uNIL2,self|...}

TABSTOP will cause the object (Xbase Part) to be set when using
the Tab key.  Note: When logical groups are defined in a dialog
using TABGROUP <nTabGroup>, TABSTOP is usually set to .T. (true)
for the first dialog element in the group.  This allows the first
dialog element of a group to be activated using the Tab key.

NOTABSTOP will cause the object (Xbase Part) to be ignored when
using the Tab key. This clause is needed only to override any
default setting of TabStop by the DCGETOPTIONS [TABSTOP] command.

TABGROUP <nTabGroup> allows objects (Xbase Parts) that are created
immediately after one another in the GetList to be combined into
logical groups. This allows the user to navigate within a dialog
from group to group by pressing the Tab key.  Within a group of
dialog elements navigation is performed using the cursor keys.

Only constants defined in the XBP.CH file can be used as values
for this instance variable.  The following table lists the
available constants:

#define constants for <nTabGroup>:

 Constant             Description

 XBP_NO_GROUP     *)  Dialog element does not belong to a group
 XBP_BEGIN_GROUP      Dialog element is the first in a group
                      (this begins the definition of the group)
 XBP_WITHIN_GROUP     Dialog element is within a group
 XBP_END_GROUP        Dialog element is the last in a group
                      (this ends the definition of the group)

*) Default value

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

RESIZE <aResize> is an optional array of two (2) elements
used for resizing and repositioning the object when the parent
is resized.

NOTE: RESIZE is to be used in conjunction with the RESIZE clause
      of DCGETOPTIONS. See the RESIZE clause of DCGETOPTIONS for
      examples.

DRAG <bDrag> is a codeblock to evaluate when the left mouse button
is clicked in the object and the drag is started.  The return
value of the code block will be stored in memory to be later
retrieved by the Drop operation. A pointer to the clicked on
object is passed to the code block.

DIALOG <bDD> is a codeblock that will evaluate when the drag is
started.  This is used to call a function that will create a
dialog window which will move with the mouse during the drag.
The dialog window will be destroyed upon the drop operation
or the release of the mouse.

Ex: DRAG {|o|o:getData()} DIALOG {|mp1,mp2,oXbp|DragDialog(mp1,mp2,oXbp)} ;

DROP <bDrop> is a codeblock to evaluate when the left mouse button
is released in the object and the drag is ended.  A pointer to
the object and the value stored in memory at the start of the
Drag are passed to the code block.

CURSOR <nDropCursor> is the mouse cursor that will show when it
is moved over this object during a drag operation.

Ex: DROP {|o,x|o:setData(x),o:invalidateRect()} ;
       CURSOR CURSOR POINTER_DATADROP_ASSIGN

Notes:

Another method of creating "custom" eXPress++ commands is to create "User-Defined Commands" which operate on the GetList system and are processed by DC_ReadGUI().

Examples:

 #include "dcdialog.ch"

 PROCEDURE Xtest()

 LOCAL GetList := {}, oBanner, bCustom, oTabPage

 @ 3,3 DCTABPAGE oTabPage CAPTION 'Banner'  SIZE 70, 10

 bCustom := {|a,b,c,d,e|DemoBanner(a,b,c,d,e)}

 @ 4,5 DCSAY 'Move the mouse across the banner' PARENT oTabPage

 @ 5,5 DCCUSTOM bCustom PARENT oTabPage OBJECT oBanner ;
   CAPTION 'This is a custom Banner object that scrolls from left to ' + ;
           'right and right to left when the mouse is moved across the banner' ;
   SIZE 62,2 FONT "20.Helv.Bold" ;
   PRESENTATION { { XBP_PP_FGCLR, GRA_CLR_DARKRED }, ;
                  { XBP_PP_BGCLR, GRA_CLR_WHITE } }

 DCREAD GUI ;
   TITLE 'Banner on a Tabpage' ;
   FIT ;
   ADDBUTTONS

 RETURN

/* ---- Custom Class ----------------- */

CLASS XbpBanner FROM XbpStatic

   EXPORTED:

   VAR    ScrollMouseCol          // Last Scroll Mouse Column
   VAR    ScrollType              // Scroll Type
   VAR    ScrollPos               // Scroll Position
   VAR    ScrollCaption           // Scroll Caption
   VAR    ScrollNum               // Scroll number

   METHOD Init, Create
   METHOD Scroll

ENDCLASS

/* ------------------- */

METHOD XbpBanner:Create( oParent, oOwner, aPos, aSize, aPP, lVisible )

::XbpStatic:Create( oParent, oOwner, aPos, aSize, aPP, lVisible )

RETURN self

/* --------------------- */

METHOD XbpBanner:Init( oParent, oOwner, aPos, aSize, aPP, lVisible )

DEFAULT aPP := {}

* initialize base class
::XbpStatic:init( oParent, oOwner, aPos, aSize, aPP, lVisible )

::scrollPos       := 1
::scrollType      := 1
::scrollCaption   := ''
::scrollMouseCol  := 0
::scrollNum       := 3
::motion := { | aPos | ::Scroll( aPos[1] ) }

RETURN self

/* --------------------- */

METHOD XbpBanner:Scroll( nMouseCol )

::SetCaption( Substr(::scrollCaption,::scrollPos) )
IF nMouseCol > ::scrollMouseCol .AND. ::scrollPos < Len(::scrollCaption)-15
  ::scrollPos += ::scrollNum
  ELSEIF nMouseCol < ::scrollMouseCol .AND. ::scrollPos > 1
  ::scrollPos -= ::scrollNum
ENDIF
::scrollMouseCol := nMouseCol
RETURN self

/* --------------------- */

STATIC FUNCTION ;
  DemoBanner ( GetList, nGetPointer, oParent, aPos, aSize, aLocals )

LOCAL oXbp

oXbp := XbpBanner():new( oParent, , aPos, aSize, ;
          GetList[nGetPointer,aGETLIST_PRESENTATION], .t., ;
          GetList, nGetPointer )

oXbp:scrollType    := Getlist[nGetPointer,nGETLIST_SUBTYPE]
oXbp:scrollCaption := GetList[nGetPointer,cGETLIST_CAPTION]
oXbp:scrollNum     := 10
IF !Empty(Getlist[nGetPointer,cGETLIST_FONT])
  oXbp:SetFontCompoundName( Getlist[nGetPointer,cGETLIST_FONT] )
ENDIF
oXbp:clipSiblings := .T.
oXbp:caption := oXbp:scrollCaption
oXbp:create()
RETURN oXbp

Files:

DCDIALOG.CH

See Also:

   USER-DEFINED COMMANDS


@ DCDIALOG

Create a DIALOG object for displaying with GUI reader

The command @..DCDIALOG creates a new Dialog object and adds the object to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> @..DCDIALOG objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCRADIO, @..DCPUSHBUTTON, @..DCMULTILINE, etc.<br><br>

Syntax:

 @ <nRow>,<nCol> DCDIALOG <oDialog>  ;
   [DRAWINGAREA <oDrawingArea>] ;
   [FONT <bocFont>] ;
   [CAPTION,TITLE <cTitle>] ;
   [BITMAP <nBitMap>] ;
   [ICON <nIcon>] ;
   [COLOR <bncFgC> [,<ncBgC>] ] ;
   [PARENT <oParent>] ;
   [PARENTID <cParentId>] ;
   [SIZE <nWidth> [,<nHeight>]] ;
   [PIXEL] ;
   [PRESENTATION <aPres>] ;
   [CARGO <xCargo>] ;
   [CURSOR <naCursor>] ;
   [PREEVAL <bPreEval>] ;
   [EVAL <bEval>] ;
   [RELATIVE <oRel>] ;
   [WHEN <bWhen>] ;
   [HIDE <bHide>] ;
   [ID <cId>] ;
   [MODAL] ;
   [VISIBLE] ;
   [INVISIBLE] ;
   [NOMINBUTTON,NOMINIMIZE] ;
   [NOMAXBUTTON,NOMAXIMIZE] ;
   [GROUP <cGroup>] ;
   [MENU <acMenu> [MSGBOX <oMsgBox>]] ;
   [BORDER <nBorder>]                 ;
   [NOTITLEBAR]         ;
   [NORESIZE]             ;
   [NOTASKLIST]         ;
   [MINSIZE <nMinCol>, <nMinRow>]     ;
   [MAXSIZE <nMaxCol>, <nMaxRow>] ;
   [AUTORESIZE] ;
   [FIT [FITPAD <nFitPad>]] ;
   [SETAPPWINDOW] ;
   [RESIZE <aResize> [SCALEFONT] ] ;
   [RESTYPE <cResType>] ;
   [RESFILE <cResFile>] ;
   [NORESTORE] ;
   [DRAG <bDrag> [DIALOG <bDD>] ;
   [DROP <bDrop> [CURSOR <nDropCursor>] ;
   [SUBCLASS <cSubClass>] ;
   [SCROLLBARS <nScrollBars>]

Arguments:

<nRow>, <nCol> are the coordinates on the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE <oRel> argument is
used.  If no parent is assigned, then the parent is the Dialog
box.  IF the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel mode by
including PIXEL as a command argument.

<oDialog> is the name of the variable to assign as a storage
place for this object or the drawingArea of this object.  If
the DRAWINGAREA <oDrawingArea> clause is used, then <oDrawingArea>
will contain a pointer to XbpDialog():drawingArea and
<oDialog> will contain a point to XbpDialog().  If the
DRAWINGAREA clause is not used, then <oDialog> will contain a
pointer to XbpDialog():drawingArea and the only method for
obtaining a pointer to the XbpDialog() will be via
<oDialog>:setParent().

SIZE <nWidth>,<nHeight> is the width and height of the
prompt.  If the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based numbers.

FONT <cFont> is a character string defining an optional font.
The font string must conform to the Xbase++ standard, ie.
"10.Courier Bold". It may also be a font object or a code block
that returns a character string or a font object to later
refresh with DC_GetRefresh().

CAPTION <cTitle> is the title which is displayed in the title
area of the Dialog window.

BITMAP <nBitmap> is the resource ID of a Bitmap that is linked
into the .EXE.  This bitmap will be sized to fill the main dialog
window.

ICON <nIcon> is the resource ID of the ICON to place in the upper
left corner of the dialog window.

COLOR <ncFGc>, <ncBGc> are foreground and background colors.
They may be character strings representing valid text-based
colors supported by SetColor() or they may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH.  If <bncFGc> is a
code block is must return a 2-element array containing a
foreground and background color.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.  If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the Browse object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the object will be disabled and grayed.
If the value returned is .TRUE. then the object will be enabled.
The object is passed as a parameter to the code block.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.
The object is passed as a parameter to the code block.

ACCELKEY <nKey> is a numeric "hot-key" assignment that will set
focus to the browse object when the hot-key is pressed.  The key
must be a valid key with the prefix xbeK_*.  These keys are
defined in APPEVENT.CH.

GOTFOCUS <bGotFocus> is a code block that is evaluated when this
object receives input focus.  <bGotFocus> := {|uNIL1,uNIL2,self|...}

LOSTFOCUS <bLostFocus> is a code block that is evaluated when this
object loses input focus.  <bLostFocus> := {|uNIL1,uNIL2,self|...}

CURSOR <naCursor> may be either a numeric value or an array of
3 elements which defines an optional mouse pointer to use for
this object.  System mouse pointers start with
XBPWINDOW_POINTERTYPE_ and are defined in XPB.CH.  The default
pointer is XBPWINDOW_POINTERTYPE_POINTER.  <naCursor> may be a
numeric resource ID that points to a Bit-Map that has been
compiled with the resource compiler and linked to the .EXE.
<naCursor> may be a 3-element array described as follows:

  Element  Type  Description
  -------  ---- ---------------------------------------------
    [1]      C   Optional name of .DLL containing the pointer
                 resource.

    [2]      N   The numeric resource ID of the pointer.  If
                 element 1 is a NIL, then this resource must be
                 linked into the .EXE.

    [3]      N   The type of resource as defined in XBP.CH.

TABSTOP will cause the object (Xbase Part) to be set when using
the Tab key.  Note: When logical groups are defined in a dialog
using TABGROUP <nTabGroup>, TABSTOP is usually set to .T. (true)
for the first dialog element in the group.  This allows the first
dialog element of a group to be activated using the Tab key.

NOTABSTOP will cause the object (Xbase Part) to be ignored when
using the Tab key. This clause is needed only to override any
default setting of TabStop by the DCGETOPTIONS [TABSTOP] command.

TABGROUP <nTabGroup> allows objects (Xbase Parts) that are created
immediately after one another in the GetList to be combined into
logical groups. This allows the user to navigate within a dialog
from group to group by pressing the Tab key.  Within a group of
dialog elements navigation is performed using the cursor keys.

Only constants defined in the XBP.CH file can be used as values
for this instance variable.  The following table lists the
available constants:

#define constants for <nTabGroup>:

 Constant             Description

 XBP_NO_GROUP     *)  Dialog element does not belong to a group
 XBP_BEGIN_GROUP      Dialog element is the first in a group
                      (this begins the definition of the group)
 XBP_WITHIN_GROUP     Dialog element is within a group
 XBP_END_GROUP        Dialog element is the last in a group
                      (this ends the definition of the group)

*) Default value

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS

MENU <acMenu> is a multi-dimensional array containing an optional
menu to attach to the top of the dialog window.  The menu must
conform to the specifications of menus returned by the menu
dictionary system.  This may also be a character string of up to
8 characters containing the NAME of the menu.  See DC_MenuLoad().
MSGBOX <oMsgBox> is the message box object which will receive
PROMPT messages from the menu when the user navigates throug the
menu.

NOMINBUTTON will suppress the painting of a minimize button on
the dialog window.

NOMAXBUTTON will suppress the painting of a maximize button on
the dialog window.

BORDER <nBorder> defines the border type of the dialog window.
Constants defined in the XBP.CH file can be assigned to <nBorder>.
The following table shows the valid #define constants.

 Constant                            Description

 XBPDLG_NO_BORDER                    No border
 XBPDLG_SIZEBORDER                   Window is sizeable
 XBPDLG_THINBORDER               *)  Thin border, window size
                                     cannot be changed
 XBPDLG_DLGBORDER                    Thick border, window size
                                     cannot be changed
 XBPDLG_RAISEDBORDERTHICK       **)  Thick, raised border

 XBPDLG_RAISEDBORDERTHIN         *)  Thin, raised border
 XBPDLG_RECESSEDBORDERTHICK          Thick, recessed border
 XBPDLG_RECESSEDBORDERTHIN       *)  Thin, recessed border
 XBPDLG_RAISEDBORDERTHICK_FIXED      Thick, raised border,
                                     size cannot be changed
 XBPDLG_RAISEDBORDERTHIN_FIXED   *)  Thin, raised border,
                                     size cannot be changed

 XBPDLG_RECESSEDBORDERTHICK_FIXED    Thick, recessed border,
                                     size cannot be changed
 XBPDLG_RECESSEDBORDERTHIN_FIXED *)  Thin, recessed border,
                                     size cannot be changed

*) not supported by Windows    **) Default border

If a dialog is embedded as MDI client within another dialog,
Windows ignores all border styles except XBPDLG_RAISEDBORDERTHICK
and XBPDLG_RECESSDBORDERTHICK. In all other cases, a border is
displayed for MDI clients that corresponds to
XBPDLG_RAISEDBORDERTHICK.

NOTASKLIST will insure that the dialog window is not placed on
the Windows task bar.

MINSIZE <nMinWidth>, <nMinHeight>  is used to establish the
minimum size of the dialog window, in pixels,  if the operator
attempts to resize the window.  A value of -1 will set the height
or width to the height or width that was automatically set by the
FIT clause of DCREAD GUI.

MAXSIZE <nMaxWidth>, <nMaxHeight> is used to establish the
maximum size of tyhe dialog window, in pixels,  if the operator
attempts to resize the window. A value of -1 will set the height
or width to the height or width that was automatically set by the
FIT clause of DCREAD GUI.

NORESIZE will prevent the operator from resizing the dialog
window.

NOTITLEBAR will prevent a titlebar from displaying on the
dialog window.  This will also prevent the minimize, maximize,
and close buttons from appearing.

AUTORESIZE is used to automatically resize and reposition all
child objects so they use the real estate of the parent dialog
in the same proportions as the child objects before the parent
was resized.  The complete childlist tree is resized.  If it
is desired to NOT resize ToolBars and Pushbuttons, then the
:resize callback of the dialog object must be overwritten
rather than using the AUTORESIZE clause as shown:

 bReSize :=  {|a,b,o,x|x := SetAppFocus(), ;
                            o:drawingArea:hide(), ;
                            DC_AutoReSize(a,b,o,GetList,.f.), ;
                            o:drawingArea:show(), ;
                            SetAppFocus(x) }

 @ .. DCDIALOG .. EVAL {|o| o:resize := bReSize }

NOTE: AUTORESIZE will not resize or reposition anything on a
dialog that was painted with a Gra*() function or a DCGRA*
command.

FIT will automatically form the dialog screen to fit comfortably
around the objects within the dialog.  This option allows the
programmer to use coordinates on dialog objects for relative
addressing only without worrying about how the objects relate to
the borders of the main dialog.  After all the objects are
created, the main dialog borders will be sized to fit the
objects.  The amount of dead space padding is set by using the
FITPAD clause.  The default is 10 pixels.

SETAPPWINDOW is important for proper modality.  If your dialog
calls popup windows in validations, popup buttons, etc. you
will want to insure that the called window is MODAL.  If you
use the MODAL clause in the DCREAD GUI command of a popup
window it will not work properly unless the calling window is
the "application window".  This is accomplished with the
SETAPPWINDOW clause.  When returning from DCREAD GUI the
application window will be restored to the previous setting.

RESIZE <aResize> is an optional array of two (2) elements
used for resizing and repositioning the object when the parent
is resized.

NOTE: RESIZE is to be used in conjunction with the RESIZE clause
      of DCGETOPTIONS. See the RESIZE clause of DCGETOPTIONS for
      examples.

      The optional SCALEFONT clause will automatically scale the
      font size up or down when the object is resized.

RESTYPE <cResType> provides support for bitmap resources of type
BMP, PNG, GIF and JPEG that have been linked into a .RES file to
be used as the caption.

Example:

@ .. DCPUSHBUTTON CAPTION 2000 RESTYPE GIF

// myres.arc
USERDEF GIF
2000 = FILE ".\GIFChart.GIF"

RESFILE <cResFile> is the name of the .DLL that contains the
resource stated in the RESTYPE <cResType> clause.  If this parameter
is not used, then the resource must be in the .EXE.

NORESTORE will cause the dialog size and location to not be
saved and restored in the event that the DC_AutoRestoreWindow()
function is used.

DRAG <bDrag> is a codeblock to evaluate when the left mouse button
is clicked in the object and the drag is started.  The return
value of the code block will be stored in memory to be later
retrieved by the Drop operation. A pointer to the clicked on
object is passed to the code block.

DIALOG <bDD> is a codeblock that will evaluate when the drag is
started.  This is used to call a function that will create a
dialog window which will move with the mouse during the drag.
The dialog window will be destroyed upon the drop operation
or the release of the mouse.

Ex: DRAG {|o|o:getData()} DIALOG {|mp1,mp2,oXbp|DragDialog(mp1,mp2,oXbp)} ;

DROP <bDrop> is a codeblock to evaluate when the left mouse button
is released in the object and the drag is ended.  A pointer to
the object and the value stored in memory at the start of the
Drag are passed to the code block.

CURSOR <nDropCursor> is the mouse cursor that will show when it
is moved over this object during a drag operation.

Ex: DROP {|o,x|o:setData(x),o:invalidateRect()} ;
       CURSOR CURSOR POINTER_DATADROP_ASSIGN

SUBCLASS <cSubClass> is a string containing a class name that
will be used to create the class, rather than DC_XbpDialog().
This class should inherit from DC_XbpDialog().
See the example in \exp19\samples\subclass.

SCROLLBARS <nScrollBars> will cause scrollbars to automatically
appear in the drawingArea of the dialog window if a child object
is displayed outside the drawing area.

Notes:

The dialog object created by @ DCDIALOG is an object of the XbpDialog() class, therefore it can be manipulated with any iVar or method supported by XbpDialog().

Examples:

 /*
 This example demonstrates both a database browse and an
 array browse in the same dialogue screen.  The database
 browse is on Tab Page 1 and the Array browse (directory
 listing) is on Tab Page 2.
 */

 #include "dcdialog.ch"
 #include "xbp.ch"

 PROCEDURE Xtest()

 LOCAL GetList := {}, GetOptions, oTabPage1, oTabPage2, ;
       oBrowse, cAlias, aDirectory, oDirectory

 USE COLLECT NEW SHARED

 /* ---- Tab Page #1 ---- */

 @ 3,3 DCTABPAGE oTabPage1 CAPTION 'Browse' ;
   SIZE 60,12

 cAlias := "BASEBALL"

 @ 2,2 DCBROWSE oBrowse PARENT oTabPage1  ;
       DATA cAlias SIZE 55,9 FREEZELEFT { 1, 2 }

 DCBROWSECOL FIELD COLLECT->descrip ;
   HEADER "Description" PARENT oBrowse

 DCBROWSECOL FIELD COLLECT->type ;
   HEADER "Type" PARENT oBrowse

 DCBROWSECOL FIELD COLLECT->sub_type ;
   HEADER "SubType" PARENT oBrowse

 DCBROWSECOL FIELD COLLECT->location ;
   HEADER "Location" PARENT oBrowse

 DCBROWSECOL DATA {|a|a:={'Yes','No','Not Sure'},a[COLLECT->for_sale+1]} ;
   HEADER "For Sale?" PARENT oBrowse

 DCBROWSECOL FIELD COLLECT->date_orig ;
   HEADER "Orig Date" PARENT oBrowse

 DCBROWSECOL FIELD COLLECT->date_acqu ;
   HEADER "Acqu Date" PARENT oBrowse

 DCBROWSECOL FIELD COLLECT->orig_price ;
   HEADER "Acqu Price" PARENT oBrowse

 DCBROWSECOL FIELD COLLECT->appr_value ;
   HEADER "Appr Value" PARENT oBrowse

 DCBROWSECOL FIELD COLLECT->condition ;
   HEADER "Condition" PARENT oBrowse

 DCBROWSECOL DATA {||IIF(COLLECT->original,'Yes','No')} ;
   HEADER "Orig Owner?" PARENT oBrowse

 /* ---- Tab Page #2 ---- */

 @  0,0 DCTABPAGE oTabPage2 CAPTION 'Directory' ;
    RELATIVE oTabPage1

 aDirectory := Directory()

 @ 2,2 DCBROWSE oDirectory PARENT oTabPage2 ;
       DATA aDirectory SIZE 55,9

 DCBROWSECOL ELEMENT 1 HEADER "Name" PARENT oDirectory WIDTH 10

 DCBROWSECOL ELEMENT 2 HEADER "Size" PARENT oDirectory WIDTH 8

 DCBROWSECOL ELEMENT 3 HEADER "Date" PARENT oDirectory WIDTH 8

 DCBROWSECOL ELEMENT 4 HEADER "Time" PARENT oDirectory WIDTH 8

 DCREAD GUI ;
   TITLE "My COLLECTION" ;
   FIT ;
   ADDBUTTONS ;
   EVAL {||oBrowse:hide(), oBrowse:show()}

 RETURN

Files:

DCDIALOG.CH


@ DCDIRTREE

Create a DIRECTORY TREE object for displaying with GUI reader

The command @..DCDIRTREE creates a new Directory Tree object and adds the object to the array named GETLIST which is later processed by the DC_READGGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> DCDIRTREE is a dialog that consists of two parts, a DIRECTORY component and a FILES component. The directory component contains a Tree View of the directory and drives of the computer and the FILES component contains a list of the files in the selected directory that match the selected wildcard extension. <br><br> @..DCDIRTREE objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCRADIO, @..DCPUSHBUTTON, @..DCCHECKBOX or @..DCTABPAGE.<br><br>

Syntax:

@ <nRow>, <nCol> DCDIRTREE ;
    [DIRS <oDirs> [VAR <cDirVar>] [DATALINK <bDirLink>]] ;
    [FILES <oFiles> [VAR <cFileVar>] [DATALINK <bFileLink>]] ;
    [PARENT <oParent>] ;
    [EXT <ExtList,...>] ;
    [COLOR <bfgC> [, <bgC> ]] ;
    [WHEN <bWhen>] ;
    [HIDE <bHide>] ;
    [FONT <bocFont>] ;
    [SIZE <nWidth> [,<nHeight>]] ;
    [DIRSIZE <nDirWidth> [,<nDirHeight>] ;
    [DIRPOS <nDirCol>, <nDirRow> ] ;
    [FILESIZE <nDirWidth> [,<nDirHeight>] ;
    [FILEPOS <nDirCol>, <nDirRow> ] ;
    [AVAILDRIVES <cAvailDrives>] ;
    [TITLE <title>] ;
    [PREEVAL <bPreEval>] ;
    [EVAL <bEval>] ;
    [RELATIVE <oRel>] ;
    [ID <cId>] ;
    [TITLE <cTitle>] ;
    [GOTFOCUS <bGotFocus>] ;
    [LOSTFOCUS <bLostFocus>]  ;
    [TABSTOP] ;
    [NOTABSTOP] ;
    [TABGROUP <nTabGroup>] ;
    [GROUP <cGroup>] ;
    [VISIBLE] ;
    [INVISIBLE]

Arguments:

<nRow>, <nCol> are the coordinates on the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE <oRel> argument is
used.  If no parent is assigned, then the parent is the Dialog
box.  IF the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel mode by
including PIXEL as a command argument.

DIRECTORY COMPONENT

  DIRS <oDirs> is a local variable name to store the pointer
  to the object for the Directory portion of the dialog.

  VAR <cDirVar> is a local variable name to store the value
  of the directory that is chosen by the user.

  DATALINK <bDirLink> is a code block that is evaluated when
  a new directory is selected by the user.

FILES COMPONENT

  FILES <oFiles> is a local variable name to store the pointer
  to the object for the FILES portion of the dialog.

  VAR <cFileVar> is a local variable name to store the value
  of the file that is chosen by the user.

  DATALINK <bFileLink> is a code block that is evaluated when
  a new file is selected by the user.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this command if you
are placing this object onto another dialogue object.  If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

EXT <ExtList,...> is a comma-delimited list of file extensions
that will display in a picklist below the FILES portion of the
directory tree dialog.  When the user selects one of the
extensions, only files with the chosen extension will be
displayed.

COLOR <ncFGc>, <ncBGc> are foreground and background colors.
They may be character strings representing valid text-based
colors supported by SetColor() or they may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH.

FONT <font> is the name of the font to use for both the
directory and file dialog boxes. It may also be a a character
string, a font object or a code block that returns a character
string or a font object to later refresh with DC_GetRefresh().

SIZE <nWidth>,<nHeight> is the width and height of the
listbox.  If the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based numbers.  The DIRECTORY dialog component occupies
60% of the total width and the FILES dialog component occupies
40% of the total width unless a DIRSIZE argument is used.

DIRPOS <nDirCol> and <nDirRow> is the position within the window
of the DIRECTORY component.

DIRSIZE <nDirWidth> and <nDirHeight> is the size of the
DIRECTORY dialog component.  If the PIXEL option is set to
.TRUE. in DCGETOPTIONS, then the width is is pixels otherwise
it is in standard text-based numbers.  If <nDirWidth> is equal
to or greater than <nWidth> above, then there will be no FILE
COMPONENT displayed.

FILEPOS <nFileCol> and <nFileRow> is the position within the window
of the FILES component.

FILESIZE <nFileWidth> and <nFileHeight> is the size of the
FILES dialog component.  If the PIXEL option is set to
.TRUE. in DCGETOPTIONS, then the width is is pixels otherwise
it is in standard text-based numbers.

AVAILDRIVES <cAvailDrives> is a character string containing the
letters of all drives which are available for browsing.  For
example the string "CDEHIJK" will prevent the floppy drives
(A and B) from being accessed.  The default is all drives.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Tree View objects are created.  The FILE object is
passed to the code block.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.
The object is passed as a parameter to the code block.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the object will be disabled and grayed.
If the value returned is .TRUE. then the object will be enabled.
The object is passed as a parameter to the code block.

GOTFOCUS <bGotFocus> is a code block that is evaluated when this
object receives input focus.  <bGotFocus> := {|uNIL1,uNIL2,self|...}

LOSTFOCUS <bLostFocus> is a code block that is evaluated when this
object loses input focus.  <bLostFocus> := {|uNIL1,uNIL2,self|...}

TABSTOP will cause the object (Xbase Part) to be set when using
the Tab key.  Note: When logical groups are defined in a dialog
using TABGROUP <nTabGroup>, TABSTOP is usually set to .T. (true)
for the first dialog element in the group.  This allows the first
dialog element of a group to be activated using the Tab key.

NOTABSTOP will cause the object (Xbase Part) to be ignored when
using the Tab key. This clause is needed only to override any
default setting of TabStop by the DCGETOPTIONS [TABSTOP] command.

TABGROUP <nTabGroup> allows objects (Xbase Parts) that are created
immediately after one another in the GetList to be combined into
logical groups. This allows the user to navigate within a dialog
from group to group by pressing the Tab key.  Within a group of
dialog elements navigation is performed using the cursor keys.

Only constants defined in the XBP.CH file can be used as values
for this instance variable.  The following table lists the
available constants:

#define constants for <nTabGroup>:

 Constant             Description

 XBP_NO_GROUP     *)  Dialog element does not belong to a group
 XBP_BEGIN_GROUP      Dialog element is the first in a group
                      (this begins the definition of the group)
 XBP_WITHIN_GROUP     Dialog element is within a group
 XBP_END_GROUP        Dialog element is the last in a group
                      (this ends the definition of the group)

*) Default value

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS

Notes:

The Directory object and File object created by @ DCDIRTREE are objects of the XbpTreeView() class, therefore they can be manipulated with any iVar or method supported by XbpTreeView().

Examples:

#include "dcdir.ch"

PROCEDURE XTest( )

LOCAL GetList := {}, oDirs, oFiles, cFileName, ;
      oFileName, cDirectory

cFileName := Space(30)
cDirectory := ''

@ 2,1 DCGET cFileName GETSIZE 40 GETOBJECT oFileName

@ 3.5,1 DCDIRTREE ;
       DIRS oDirs VAR cDirectory ;
       FILES oFiles VAR cFileName DATALINK {||oFileName:SetData()} ;
       SIZE 40,10.5 ;
       EXT '*.ICO','*.BMP','*.JPG','*.*'

DCREAD GUI ;
   TITLE 'eXPress++ Demo Program' ;
   FIT ;
   ADDBUTTONS

RETURN

Files:

DCDIR.CH

See Also:

   dc_popdir()


@ DCFINDBROWSE

A browse-window find utility that uses AutoSeek

@ DCFINDBROWSE is a utility command that paints a browse with user-defined columns and a entry GET for the user to enter keyboard characters. The keys entered will automatically seek the selected index and refresh the browse. The user can click the right mouse button on a column heading to select a different index. The Up, Down, Page Up, Page Down, Ctrl Page Up, Ctrl Page Down and Enter keys are all enabled while the user is in the entry GET to allow the user to navigate the browse with keys or the mouse or enter keys for seeking.

Syntax:

 @ [ <nRow>,<nCol> ] DCFINDBROWSE ;
         FIELDS <aFields> ;
         [PARENT <oParent>] ;
         [SIZE <nWidth>, <nHeight>] ;
         [TITLE <cTitle>] ;
         [AUTOSEEK] ;
         [PIXEL] ;
         [DATA <acbData>] ;
         [POINTER <nPointer>] ;
         [EVAL <bEval>] ;
         [PRESENTATION <aPres>] ;
         [NOHEADERS] ;
         [NOHSCROLL] ;
         [NOVSCROLL] ;
         [EXIT] ;
         [SEEKDELAY <nDelay>] ;
         [TO <lStatus>] ;
         [FONT <cFont>] ;
         [LEFTBUTTONSORT] ;
         [POPUP <bPopUp>] ;
         [SAYINDEXFONT <cSayIndexFont>]

Arguments:

FIELDS <aFields> is a multidimensional array that defines the
columns of data to browse.

Element   Type   Description
-------   ----- ---------------------------------------------
  [1]       B    Code Block (ex: {||CUSTOMER->name})

  [2]       C    Header (ex: "Customer Name")

  [3]       N    Column Width (ex: 10)

  [4]       C    Index Name or Tag (ex: "CUSTNAME")

  [5]       C    Index Prompt (ex: "Customer Name")

  [6]      C/B   Prefix for AutoSeek

  [7]       B    Seek string code block. User input buffer
                 is passed to this code block and return
                 value of code block is used for the seek.
                 ex: {|c|Right(Space(7)+Alltrim(cString),7)}

  [8]       C    Picture clause.

Note: Only elements 1 and 2 are required.

PARENT <oParent> is the Parent window to paint the objects.
If no parameter is passed a  modal window will be created.

<nRow> and <nCol> are the starting coordinates from the top
left of the parent window to paint the objects. These are text
based coordinates which may include decimals.  If no parent
parameter is passed, these arguments are not needed.

SIZE <nWidth>, <nHeight> are the width and height of the window
in text-based coordinates.  The defaults are 65 columns and
15 rows.

TITLE <cTitle> is the title to display in the titlebar area of the
dialog window.

AUTOSEEK will include a GET for the user to enter keys to seek
automatically.  If this argument is not used then only a browse
will be displayed.  The prefix value of the selected column is
inserted before the seek string.  This may be a code block or
a string.  If it is a code block it must return a string when
evaluated.

NOHEADERS will suppress the display of headers and the horizontal
scroll bar in the browse.

PIXEL assumes coordinates are pixel-based, otherwise they are
text-based.

DATA <acbData> is the data source.  If it is a code block it
must return an Alias() or an array when evaluated.  If it is
an alias the database must already be opened.  If it is an
array, the array must be two-dimensional.

POINTER @<nPointer> is a numeric variable (passed by reference)
to store the array element selected when the user double-clicks
on the browse or presses ENTER.  Used when browsing arrays only.

EVAL <bEval> is a code block to evaluate after the Browse
object is created and just before invoking the event handler.
The parent dialog object and the browse object are passed as
parameters: {|oDlg,oBrowse|...}

PRESENTATION <aPres> is a two-element array of two subarrays.
The first element is a Presentation Parameters array that
follows the Xbase++ specification for Browse Presentation
parameters.  The second element is a two-element array :

{ aHeaderFG, aHeaderBG }

 <aHeaderFG> and <aHeaderBG> are the foreground and background
 colors of the selected column.  This is the column selected by
 the user for sorting or selecting an index.

NOHSCROLL will suppress the horizontal scrollbar and not allow
resizing of columns.

NOVSCROLL will suppress the vertical scroll bar.

EXIT exit without destroying the dialog window.

SEEKDELAY <nSeekDelay> is the number of seconds after a key is
pressed to wait before performing the seek.  This allows a
string to be typed without performing a seek everytime a key
is pressed. The default is .1 seconds.  If <nSeekDelay> is 0
then the seek is not performed until the ENTER key is pressed.

TO <lStatus> is a variable to store a logical value that is
returned by the DC_FindBrowse() function.  If the user exits
by selecting an item, <lStatus> will contain a .TRUE. value
otherwise it will be .FALSE.

FONT <cFont> is the Font Compound Name to use for the browse
columns.

LEFTBUTTONSORT will allow the operator to use the left mouse
button on the column headers to select the sort order, otherwise
only the right button will be enabled for sorting and the left
button will allow for sizing the columns.

POPUP <bPopUp> is a code block to evaluate.  If this variable is
a code block, a popup button will be placed to the right of the
GET used for entering a seek value.  If the user clicks on this
button or presses CTRL-ENTER while in the GET, the code block
will be evaluated.  The value in the GET is passed to the code
block and the value returned by the code block is stuffed back
into the GET.

SAYINDEXFONT <cSayIndexFont> is the font of the Index Name prompt
to the right of the search window.

Examples:

// Example 1 - Popup a Browse with multiple columns and AutoSeek

FUNCTION XTest()

LOCAL GetList := {}, oBrowse, aFields, aHeaders, aPres, nRecord

SET DEFA TO ..\XDOC
USE EXPRESS VIA FOXCDX EXCLUSIVE ALIAS 'XDOC'
SET INDEX TO EXPRESS.CDX
OrdSetFocus('COMMAND')
SET DEFA TO

aFields := {}

DCFINDADDCOL DATA {||XDOC->command} TAG 'COMMAND' PROMPT 'Command' ;
   HEADER 'Command' TO aFields

DCFINDADDCOL DATA {||XDOC->short} HEADER 'Short' TO aFields

DCFINDADDCOL DATA {||XDOC->type} HEADER 'Type' TO aFields  ;
   TAG 'TYPE' PROMPT 'Type'

DCFINDADDCOL DATA {||XDOC->module} HEADER 'Module' TO aFields  ;
   TAG 'TYPE' PROMPT 'Type' TO aFields

DCFINDADDCOL DATA {||XDOC->see_also} HEADER 'See Also' TO aFields

@ DCFINDBROWSE FIELDS aFields DATA 'XDOC' SIZE 50,10 AUTOSEEK

RETURN nil

Files:

DCDIALOG.CH

See Also:

   dc_findbrowse()
   DCFINDADDCOL


@ DCGET

Create a GET object for displaying with the text/GUI reader

The command @..DCSAY...GET creates a new GET definition and adds it to the array named GETLIST which is later processed by the DC_Read*() functions or by the DCREAD * commands. The GETLIST array must be first declared and initialized to the value of {}. <br><br> The command DCREAD GUI creates the DC_Xbp*() objects and activates the edit mode for all definitions found in the GetList array. <br><br> The command DCREAD HTML creates the DC_Html*() objects and writes the HTML source code.<br><br> A Get object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> @..DCSAY..GET works nearly identical to the standard Xbase++ command @..SAY..GET except for a major difference. The GetList array has a new structure that supports a more robust dialog system. <br><br> @..DCSAY..GET objects can be combined with any objects that that use the DCDIALOG system, such as @..DCCHECKBOX, @..DCRADIO, @..DCBUTTON or @..DCTABPAGE.

Syntax:

@ <nRow>,<nCol> DCGET <uVar> ;
  * [DATALINK <bLink>] ;
    [GETCOLOR <bncFgC>,[<ncBgC>] ] ;
  * [GETSIZE <nWidth> [,<nHeight>]] ;
    [PARENT <oParent>] ;
    [PARENTID <cParentId>] ;
    [MESSAGE <bcMsg> [INTO <oMsgBox>]] ;
    [VALID <bValid>] ;
    [POPUP <bPopUp>] ;
       [POPCAPTION <ncaCaption] ;
       [POPFONT <cPopFont>] ;
       [POPWIDTH <nPopWidth>] ;
       [POPHEIGHT <nPopHeight>] ;
       [POPSTYLE <nPopStyle>] ;
       [POPKEY <anPopKey> ;
       [POPTABSTOP] ;
       [POPGLOBAL] ]  ;
       [POPTOOLTIP <bcPopToolTip>] ;
       [POPWHEN <bPopWhen>] ;
       [POPHIDE <bPopHide>] ;
    [HELPCODE <cHelp>] ;
  * [PICTURE <bcPicture>] ;
    [GETFONT <bocFont>] ;
  * [UNREADABLE] ;
    [PASSWORD [PASSCHAR <cPassChar>] [SHOWLASTCHAR] ;
  * [CONFIRM] ;
  * [NOCONFIRM] ;
    [HIDE <bHide>] ;
    [WHEN <bWhen>] ;
  * [EDITPROTECT <bProtect>] ;
  * [PIXEL] ;
  * [GETPRESENTATION <aPres>] ;
    [GETTOOLTIP <bcToolTip>] ;
    [GETOBJECT <oObject>] ;
  * [CURSOR <naCursor>] ;
    [CARGO <xCargo>] ;
    [PREEVAL <bPreEval>] ;
    [EVAL <bEval>] ;
    [RELATIVE <oRel>] ;
    [GETID <cId>] ;
    [TITLE <cTitle>] ;
  * [ACCELKEY <anAccel>] ;
  * [GOTFOCUS <bGotFocus>] ;
  * [LOSTFOCUS <bLostFocus>] ;
  * [TABSTOP]  ;
  * [NOTABSTOP];
  * [TABGROUP <nTabGroup>] ;
  * [VISIBLE] ;
  * [INVISIBLE] ;
    [GROUP <cGroup>] ;
  * [KEYBLOCK <bKeyBlock>] ;
  * [PROPER [PROPOPTIONS <aPropOptions>]] ;
  * [COMBO ;
       [HEIGHT <nComboHeight>] ;
       [WIDTH <nComboWidth>] ;
       [DATA <acbComboData>]        ;
       [FIELD <bField>] ;
       [ELEMENT <nElement>] ;
       [RETURN <bReturn>] ;
       [CAPTION <oncComboCaption>] ;
       [FONT <ocComboButtonFont>] ;
       [LISTFONT <ocComboListFont>] ;
       [LISTPRESENTATION <aListPres>] ;
       [HOTKEY <nComboHotKey>] ] ;
       [KEYDROP] ;
    [NAME <cVarName>] ;
  * [CALCULATOR] ;
    [RESIZE <aResize> [SCALEFONT] ] ;
    [DRAG <bDrag> [DIALOG <bDD>] ;
    [DROP <bDrop> [CURSOR <nDropCursor>] ;
    [SUBCLASS <cSubClass>] ;
    [ALIGN <nAlign>]

Arguments:

GUI applications:

<nRow> and <nCol> are the row and column of the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE <oRel> argument is
used.  If no parent is assigned, then the parent is the Dialog
box. IF the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel
mode by including PIXEL as a command argument.

<nRow> may be assigned the value DCGUI_ROW.  This will paint
the object at the same row as the previous object.  It is
provided to emulate the Row() function in text-based applications.

<nCol> may be assigned the value DCGUI_COL + <nOffset>.  This
will paint the object immediately to the right of the previous
object plus <nOffset> pixels.  It is provided to emulate the Col()
function in text-based applications.

HTML applications:

<nRow> and <nCol> are the row number and column number of
the table if the parent of this object is a DCTABLE. The
text will be inserted in the cell of the table defined by
the row/column.

GET <uVar> is the variable to GET.  This may be a variable
of any type except an object or array. It must not be a macro.
The <uVar> is automatically anchored via a Get-Set codeblock
created by DC_GetAnchorCB() unless <uVar> is a custom Get-Set
code block. Macros may be used in a custom Get-Set code block.

OBJECT | GETOBJECT <oObject> is the variable to use as a container
for the object after it is created by the GUI reader.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

DATALINK <bLink> is an optional code block that is evaluated
every time Get/Set codeblock is evaluated, ie when the data
is read from the <uVar> into the object except when using
a user-defined Get/Set code block.  <bLink> is also
evaluated when DC_GetRefresh() is called unless the <lDataLink>
parameter of DC_GetRefresh() is .FALSE.

CARGO | GETCARGO <xCargo> is any kind of data you wish to to add
to the :cargo container for this object.  The cargo may be
accessed at any time via the :cargo exported variable, however
it will not be stored in the same manner it is entered.  The
:cargo container of DCDIALOG objects is an array of at least
three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

FONT | GETFONT <cFont> is a character string defining an optional
font. The font string must conform to the Xbase++ standard, ie.
"10.Courier Bold". It may also be a font object or a code block
that returns a character string or a font object to later
refresh with DC_GetRefresh().

SIZE | GETSIZE <nGetWidth> [,<nGetHeight>]] is the size to
allocate to the GET variable.  If the PIXEL option is set to
.TRUE. in DCGETOPTIONS, then the size must be entered in
pixels otherwise it must be entered in standard text
length.  If no GETSIZE argument is used, then the get will
be automatically sized to the size established by transforming
the contents of of the get variable to a string to determine
the length of the get.   The default font for GETS in
eXpress++ is 12.Courier because this provides the best user
font for data-entry, so it is usually not necessary to use
this option unless you are also using the FONT parameter.

<nGetWidth> may be assigned the value DCGUI_PARENTWIDTH - <nOffset>.
This will set the width of the object relative to the width of its
parent.

<nGetHeight> may be assigned the value DCGUI_PARENTHEIGHT - <nOffset>.
This will set the height of the object relative to the height of its
parent.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.  If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

MESSAGE <bcMsg> is the message you want to display in the
message area of the dialogue screen defined by the DCMESSAGEBOX
command when the object is in focus.  Optionally, INTO <oMsgBox>
will designate which message box to display the message into.
If the INTO clause is not used, then the last message box in the
GetList is the default. <oMsgBox> may also be any object that
supports the :setCaption() method.  If <bcMsg> is a code-block,
it must return a character string.

PICTURE <bcPicture> is a character string specifying formatting
options for the value of <VarName> during display and editing.
If <bcPicture> is a code block, then the code block must return
a character string.  The code block is evaluated by the DC_GetRefresh()
function.

POPUP <bPopUp> will paint a mouse button at the end of the GET
variable on the screen which informs the operator than an
additional picklist will pop-up if the operator single-clicks on
the button or if the operator presses the CTRL-J or CTRL-ENTER
key while the GET has input focus.  The code block will be
evaluated when the button is clicked.  The following two
parameters are passed to the codeblock :

  1. The value in the current GET
  2. A pointer to the GET object

The value returned by the code block will be placed back in the
GET.  The code block may return an optional array of two
elements rather than a single value to store to the GET.  If a
two-element array is returned, the first element must be the
value to store in the GET and the second element must be a
pointer to the object which is to receive focus. This provides
for the ability to force the focus to a different object on a
POPUP  other than the GET.

The POPUP clause is used for popups like calendars, calculators,
picklists, etc.  The default caption on the button is three dots.
To change the caption or button display options, use the
function DC_GetPopupCaption().

POPCAPTION <ncaCaption> is the optional caption of the button.
This will override the DC_PopupCaption() setting.   This will override the
DC_GetPopupCaption() setting. If <ncaCaption> is an array, it
must be an array of 2 elements where the first element is the
bitmap resource number of the caption to display when the GET is
enabled and the second element is the bitmap resource number of
the caption to display when the GET is disabled with the WHEN
clause.

POPFONT <cFont> is the optional font of the button.  This will override the
DC_GetPopupCaption() setting.

POPWIDTH <nWidth> is the width (in pixels) of the button.  This
will override the default width.

POPHEIGHT <nHeight> is the height (in pixels) of the button.
This will override the default height. POPSTYLE <nStyle> is the
style of the popup button:

  POPSTYLE <nStyle>          Description
  -------------------------  ----------------------------------
  DCGUI_POPUPSTYLE_OUTSIDE   Button is outside and to the right
                             of the GET.
  DCGUI_POPUPSTYLE_IMBEDDED  Button is imbedded within the GET.

POPKEY <anPopKey> is a numeric key value or an array of numeric
key values that may be assigned to invoke the popup button when
the key is pressed.  An additional POPGLOBAL clause may be used
to establish that the assigned key is active regardless of the
object that is in focus, otherwise the key will be active only
when the associated get has focus.  Key values are defined in
APPEVENT.CH and start with the definition xbeK_*.

POPTABSTOP will cause the TABSTOP key to be active on the popup
button so the user may tab from the GET to the popup button.

POPTOOLTIP <bcPopToolTip> is a character string which will display
as a "Tool Tip" next to the popup button the mouse is passed
over the popup button. A semi-colon within the text indicates a new
line.  If <bcToolTip> is a code-block, it must return a character
string.  NOTE: The Tooltip painting method is run in another
thread, therefore the codeblock should not run code that points
to the current work area.  It may however, contain local, public
or private variables.

POPWHEN <bPopWhen> is a code block to evaluate to determine
whether the popup button is enabled or disabled.  If the codeblock
returns a .T., then the button is enabled, otherwise it is
disabled.

POPHIDE <bPopHide> is a code block to evaluate to determine
whether the popup button is hidden.  If the codeblock returns
a .T. then the button is hidden.

The UNREADABLE clause will cause text to be displayed as asterisks
(*) for inputting sensitive data such as passwords.

PASSWORD will cause asterisks to be displayed in place of the
value entered.  This only affects the display, not the value
entered or returned.  PASSCHAR is an optional clause to define
the character to be used as a replacement for the asterisk.
SHOWLASTCHAR is an optional clause that will show the last
character entered.

The NOCONFIRM clause will cause the GET to be exited when the
cursor reaches the end of the buffer during keyboard entry.
Normally, the GET can be exited only by pressing the ENTER key,
TAB key, UP key, DOWN key or clicked on another object.  This
overrides the setting of CONFIRM in DCGETOPTIONS.

The CONFIRM clause will cause the GET to be exited by pressing
the ENTER key.  This overrides the setting of NOCONFIRM in
DCGETOPTIONS.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the object will be disabled and grayed.
If the value returned is .TRUE. then the object will be enabled.
The object is passed as a parameter to the code block.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.
The object is passed as a parameter to the code block.

EDITPROTECT <bProtect> is an optional condition tested during the
execution of the GUI gets by the DCREAD GUI command, before the
object receives input focus (before it is activated). When the
condition returns the value .T. (true), the object receives the
input focus.  Otherwise, it is skipped. <bProtect> is a code
block that must return a logical value when evaluated. The code
block is evaluated prior to the object receiving input focus.
This clause behaves similar to the WHEN clause with the exception
that the object is not disabled (grayed out).  The object is
passed as a parameter to the code block.

VALID <bValid> is an optional condition tested during the
execution of the GUI gets by the READ command before a Get
object loses input focus (before it is deactivated).  When
the condition returns the value .T. (true), the Get object
loses the input focus.  Otherwise, it remains active. <bValid>
is a code block that must return a logical value when it is
evaluated.  The object passed as a parameter to the code block.

NOEXITVALID <bValid> is a replacement for the VALID clause.
This will insure that the <bValid> codeblock is only validated
upon lost focus, and NOT validated with the EXITVALIDATE clause
of DCGETOPTIONS.

HELPCODE <cHelp> is a character string that is passed to the
DC_HelpF1() function if F1 is pressed or the HELP button
is clicked when this GET has focus.  This HELPCODE allows
the Help system to override the passing of the Procedure and
Varname for more specific context-help.

GETPRESENTATION <aGetPres> is a two-dimensional array. If
specified, this contains presentation parameters for the GET
object.  The first column of the array must contain #define
constants from the XBP.CH file starting with the prefix
XBP_PP_. These constants define the presentation parameters
that can be set for the object and include colors and fonts.
The second column of the array in <aSayPres> contains the value
for each setting.  These are also generally set using #define
constants from the GRA.CH file.

TOOLTIP | GETTOOLTIP <bcGetToolTip> is a character string which
will display as a "Tool Tip" next to the object when the cursor
is passed over the object. A semi-colon within the text indicates
a new line.  If <bcToolTip> is a code-block, it must return a
character string.  NOTE: The Tooltip painting method is run in
another thread, therefore the codeblock should not run code that
points to the current work area.  It may however, contain local,
public or private variables.

CURSOR | GETCURSOR <naCursor> may be either a numeric value or
an array of 3 elements which defines an optional mouse pointer
to use for this object.  System mouse pointers start with
XBPWINDOW_POINTERTYPE_ and are defined in XPB.CH.  The default
pointer is XBPWINDOW_POINTERTYPE_POINTER.  <naCursor> may be a
numeric resource ID that points to a Bit-Map that has been
compiled with the resource compiler and linked to the .EXE.
<naCursor> may be a 3-element array described as follows:

  Element  Type  Description
  -------  ---- ---------------------------------------------
    [1]      C   Optional name of .DLL containing the pointer
                 resource.

    [2]      N   The numeric resource ID of the pointer.  If
                 element 1 is a NIL, then this resource must be
                 linked into the .EXE.

    [3]      N   The type of resource as defined in XBP.CH.

COLOR | GETCOLOR <ncFGc>, <ncBGc> are foreground and background
colors. They may be character strings representing valid text-based
colors supported by SetColor() or they may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH. If <bncFGc> is a
code block is must return a 2-element array containing a
foreground and background color.

GETID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

ACCELKEY <anAccel> is a numeric "hot-key" assignment that will set
focus to the checkbox object when the hot-key is pressed.  The key
must be a valid key with the prefix xbeK_*.  These keys are
defined in APPEVENT.CH.  <anAccel> may also be an array of numeric
values to assign more than one key to the object.

GOTFOCUS <bGotFocus> is a code block that is evaluated when this
object receives input focus.  <bGotFocus> := {|uNIL1,uNIL2,self|...}

LOSTFOCUS <bLostFocus> is a code block that is evaluated when this
object loses input focus.  <bLostFocus> := {|uNIL1,uNIL2,self|...}

TABSTOP will cause the object (Xbase Part) to be set when using
the Tab key.  Note: When logical groups are defined in a dialog
using TABGROUP <nTabGroup>, TABSTOP is usually set to .T. (true)
for the first dialog element in the group.  This allows the first
dialog element of a group to be activated using the Tab key.

NOTABSTOP will cause the object (Xbase Part) to be ignored when
using the Tab key. This clause is needed only to override any
default setting of TabStop by the DCGETOPTIONS [TABSTOP] command.

TABGROUP <nTabGroup> allows objects (Xbase Parts) that are created
immediately after one another in the GetList to be combined into
logical groups. This allows the user to navigate within a dialog
from group to group by pressing the Tab key.  Within a group of
dialog elements navigation is performed using the cursor keys.

Only constants defined in the XBP.CH file can be used as values
for this instance variable.  The following table lists the
available constants:

#define constants for <nTabGroup>:

 Constant             Description

 XBP_NO_GROUP     *)  Dialog element does not belong to a group
 XBP_BEGIN_GROUP      Dialog element is the first in a group
                      (this begins the definition of the group)
 XBP_WITHIN_GROUP     Dialog element is within a group
 XBP_END_GROUP        Dialog element is the last in a group
                      (this ends the definition of the group)

*) Default value

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS

KEYBLOCK <bKeyBlock> is a code block to evaluate when a key is
pressed in the GET.  The code block should be formatted as follows:
{|mp1,xNil,oXbp|MyFunc(mp1,xNil,oXbp)} where <mp1> is the
numeric value (defined in APPEVENT.CH) of the key pressed and
oXbp is the GET object.

PROPER will cause the first character of each word to be
capitalized and all other characters to be lower case.  The
optional clause PROPOPTIONS designates a two element array
for alternate behavior:

{ lProperLow, cTriggers }

lProperLow - Logical.  Force upper case characters to lower case
             If not First character in field or following trigger
             character.

cTriggers  - A list of characters after which a capital is desired.
             (ie. " '-1234567890" capitalize after space, apostrophe,
             hyphen, or any number)

COMBO is used to create a ComboBox-Style Get with a pull-down
picklist from an array or database.  HEIGHT <nComboHeight> is
the Height of the Picklist area in text rows or in pixels if
the PIXEL clause is used.  WIDTH <nComboWidth> is the width of the
picklist area in text columns or in pixels if the PIXEL clause is
used.  If the WIDTH clause is not used, then the width of the
picklist will be the same as the width of the Get.  DATA <acbComboData>
is the data source of the picklist.  <acbComboData> must be a
character string containing the Alias() of the database, a
single-dimension array, a multi-dimensional array or a code-block
which returns an alias or array. FIELD <bField> is a code block
containing the field name of the data to be shown in the picklist
(when browsing a database) or ELEMENT <nElement> is the numeric
value of the column in the array to be shown in the picklist (when
browsing an array). RETURN <bReturn> is a code block to evaluate on
return.  CAPTION <oncComboCaption> is the caption to place on the
popup button that invokes the listbox.  This may be a character
string, a numeric resource, or an XbpBitMap() object.
FONT <ocComboButtonFont> is the font to use for the pushbutton
(if the caption is a character string).  LISTFONT <ocComboListFont>
is the font to use for the listbox.  LISTPRESENTATION <aComboListPres>
is a presentation array defining the presentation parameters for
the listbox.  HOTKEY <nComboHotKey> is the hot key to use to invoke
the listbox.  KEYDROP will cause the combobox to drop down on
pressing the first key in the GET.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

NAME <cVarName> is the variable name to assign to the GET
object (for HTML based applications.)

CALCULATOR causes inputting into a numeric GET to function
exactly like the CalcSle() example of Xbase++.  The CalcSLE class
displays calculator-type entry fields for numeric values. The
display of entered data is right aligned, the number of decimal
places is unknown and the largest number to be entered is limited
by the width of the entry field.

RESIZE <aResize> is an optional array of two (2) elements
used for resizing and repositioning the object when the parent
is resized.

NOTE: RESIZE is to be used in conjunction with the RESIZE clause
      of DCGETOPTIONS. See the RESIZE clause of DCGETOPTIONS for
      examples.

      The optional SCALEFONT clause will automatically scale the
      font size up or down when the object is resized.

DRAG <bDrag> is a codeblock to evaluate when the left mouse button
is clicked in the object and the drag is started.  The return
value of the code block will be stored in memory to be later
retrieved by the Drop operation. A pointer to the clicked on
object is passed to the code block.

DIALOG <bDD> is a codeblock that will evaluate when the drag is
started.  This is used to call a function that will create a
dialog window which will move with the mouse during the drag.
The dialog window will be destroyed upon the drop operation
or the release of the mouse.

Ex: DRAG {|o|o:getData()} DIALOG {|mp1,mp2,oXbp|DragDialog(mp1,mp2,oXbp)} ;

DROP <bDrop> is a codeblock to evaluate when the left mouse button
is released in the object and the drag is ended.  A pointer to
the object and the value stored in memory at the start of the
Drag are passed to the code block.

CURSOR <nDropCursor> is the mouse cursor that will show when it
is moved over this object during a drag operation.

Ex: DROP {|o,x|o:setData(x),o:invalidateRect()} ;
       CURSOR CURSOR POINTER_DATADROP_ASSIGN

SUBCLASS <cSubClass> is a string containing a class name that
will be used to create the class, rather than DC_XbpGet().
This class should inherit from DC_XbpGet().
See the example in \exp19\samples\subclass.

ALIGN <nAlign> specifies how the characters are aligned within
the GET object. By default, they are left justified.
Constants defined in the XBP.CH file should be used for <nAlign>
The following table lists the values available for the <nAlign>
option:

Constants for <nAlign> :

  Constant       Description

  XBPSLE_LEFT    Text is displayed left justified

  XBPSLE_RIGHT   Text is displayed right justified

  XBPSLE_CENTER  Text is displayed centered

Notes:

Clauses marked by an asterisk ( * ) are not supported by DCREAD HTML or DC_ReadHtml().

------------------

GUI applications:

The GET object created by @ DCSAY..GET is an object of the DC_XbpGet() class, therefore it can be manipulated with any iVar or method supported by DC_XbpGet(). DC_XbpGet() is a non-supported class which is provided with Xbase++ as an example. This class inherits from the XbpSle() class and the Get() class. It has been modified to support features required by eXPress++. The source for DC_XbpGet() is in _DCXBPGT.PRG.

If the CHECKGET option of GETOPTIONS is used, then the GET object is an object of the DC_XbpCheckBox() class.

-----------------

HTML Applications

The GET object created by @ DCSAY..GET is an object of the DC_HtmlGet() class.

Examples:

/*  Example 1 (Simple Gets - GUI) */

#include "dcdialog.ch"

PROCEDURE Xtest_1()

LOCAL GetList := {}, cLastName := Space(15), cFirstName := Space(15),;
      cCompany := Space(25), cStreet := Space(25), cCity := Space(25),;
      cState := Space(2), cCountry := Space(20), cPhone := Space(15),;
      GetOptions

@ 5,10 DCSAY ' Last Name' GET cLastName
@ 5,40 DCSAY 'First Name' GET cFirstName
@ 7,10 DCSAY '   Company' GET cCompany
@ 8,10 DCSAY '    Street' GET cStreet
@ 9,10 DCSAY '      City' GET cCity
@11,10 DCSAY '     State' GET cState
@11,40 DCSAY '   Country' GET cCountry
@13,10 DCSAY '     Phone' GET cPhone PICT '(999)-999-9999'

DCGETOPTIONS SAYRIGHTJUST

DCREAD GUI ;
    FIT ;
    ADDBUTTONS ;
    OPTIONS GetOptions

RETURN

/*  Example 2 (Gets with Whens, Hides, Validations and Pop-ups (GUI))  */

PROCEDURE Xtest_2()

LOCAL GetList := {}, cLastName := Space(15), cFirstName := Space(15),;
      cCompany := Space(25), cStreet := Space(25), cCity := Space(25),;
      cState := Space(2), cCountry := Space(20), cPhone := Space(15),;
      dDate1 := Date(), dDate2 := Date()+1, GetOptions

@ 5,10 DCSAY ' Last Name' GET cLastName ;
       VALID {||DC_ReadEmpty(cLastName)}

@ 5,40 DCSAY 'First Name' GET cFirstName ;
       VALID {||DC_ReadEmpty(cFirstName)}

@ 7,10 DCSAY '   Company' GET cCompany

@ 8,10 DCSAY '    Street' GET cStreet ;
       VALID {||DC_ReadEmpty(cStreet)}

@ 9,10 DCSAY '      City' GET cCity ;
       VALID {||DC_ReadEmpty(cCity)}

@11,10 DCSAY '     State' GET cState PICT '@!' ;
       VALID {||DC_ReadEmpty(cState)} ;
       WHEN {||!Empty(cCity)}

@11,40 DCSAY '   Country' GET cCountry

@13,10 DCSAY '     Phone' GET cPhone PICT '(999)-999-9999'

@15,10 DCSAY 'Start Date' GET dDate1 ;
       POPUP {|d|DC_PopDate(d)}

@16,10 DCSAY '  End Date' GET dDate2 ;
       HIDE {||dDate1 = Date()}

DCGETOPTIONS SAYRIGHTJUST

DCREAD GUI ;
    FIT ;
    ADDBUTTONS ;
    OPTIONS GetOptions

RETURN

/* Example 3 (Says and Gets in HTML) */

#include "dcdialog.ch"
#include "dchtml.ch"

PROCEDURE Xtest_3()

LOCAL i, GetList[0], oForm, cHtml, oTable, cUserId, cPassword

DCFORM OBJECT oForm
DCTABLE OBJECT oTable PARENT oForm ROWS 2 COLUMNS 2 WIDTH '200'

cUserId := Space(10)
cPassword := Space(10)

@ 1,1 DCSAY 'User ID' PARENT oTable
@ 1,2 DCGET cUserId PARENT oTable NAME 'App.User'
@ 2,1 DCSAY 'Password' PARENT oTable
@ 2,2 DCGET cUserId PARENT oTable NAME 'App.Password' PASSWORD

DCREAD GUI HTML TO cHtml

MemoWrit('TEST.HTM',cHtml)

RETURN

Files:

DCDIALOG.CH

See Also:

   dc_getpopupcaption()
   @ DCSAY
   dc_getcombomode()


@ DCGRABOX

Draw a Box

The command @..DCGRABOX creates a new GraBox() object and adds the object to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the display/edit mode for all objects found in the GetList array. A Get object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD GUI command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> @..DCGRABOX objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY, @..DCCHECKBOX, @..DCRADIO, @..DCBUTTON or @..DCTABPAGE.

Syntax:

@ <nSRow>,<nSCol> TO <nERow>,<nECol> DCGRABOX ;
  [COLOR <ncFgC> [,<ncBgC>] ] ;
  [PARENT <oParent>] ;
  [PIXEL] ;
  [ATTRIBUTE <aAttr>] ;
  [RELATIVE <oRel>] ;
  [TITLE <cTitle>] ;
  [ID <cId>] ;
  [GROUP <cGroup>] ;
  [FILL <nFill>] ;
  [HRADIUS <nHrad>] ;
  [VRADIUS <nVrad>]

Arguments:

<nSRow>, <nSCol>, <nERow>, <nECol> are the row and column of
the screen.  Coordinates are always relative to position 0,0
ie. Top,Left of the parent object, unless the RELATIVE <oRel>
argument is used.  If no parent is assigned, then the parent
is the Dialog box. IF the PIXEL option is set to .TRUE. in
DCGETOPTIONS, then the numbers are in pixels otherwise they
are in standard text-based coordinates.  You can also force
the pixel mode by including PIXEL as a command argument.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.  If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

COLOR <nFGc> is the color of the box to be drawn. It must be
a numeric constant which begin with either the prefix
GRA_CLR_ or the prefix XBPSYSCLR_ as defined in GRA.CH or
XBP.CH.

ID <cId> is a unique identifier for this object.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh(),
DC_PaintGraControls() or DC_ReadGui().

ATTRIBUTE <aAttr> is an array of attributes that meets the
specification for area attributes such as color, mixmode,
pattern, etc.

<aAttr> := Array( GRA_AA_COUNT )

<aAttr> is an array whose elements contain the attributes for
character strings drawn by the function GraBoxLine().

#define constants of the attribute array for lines.

These contants are defined in GRA.CH.

#define constants of the attribute array for areas

 Array element     #define | value  Default value

 GRA_AA_COLOR      GRA_CLR_*        GRA_CLR_NEUTRAL
 GRA_AA_BACKCOLOR  GRA_CLR_*        GRA_CLR_BACKGROUND
 GRA_AA_MIXMODE    GRA_FGMIX_*      GRA_FGMIX_OVERPAINT
 GRA_AA_BGMIXMODE  GRA_BGMIX_*      GRA_BGMIX_LEAVEALONE
 GRA_AA_SYMBOL     GRA_SYM_*        GRA_SYM_SOLID

Attributes for areas

 Array element     Description

 GRA_AA_COLOR      Foreground color
 GRA_AA_BACKCOLOR  Background color
 GRA_AA_MIXMODE    Color mix attribute for foreground
 GRA_AA_BGMIXMODE  Color mix attribute for background
 GRA_AA_SYMBOL     Fill pattern

FILL <nFill> specifies whether the rectangle is drawn as an
outline or is filled. The following table shows the #define
constants from the GRA.CH file to use for <nFill> :

Fill attributes for GraBox()

 Constant         Description

 GRA_FILL         Fills rectangle
 GRA_OUTLINE *)   Only draws rectangle border
 GRA_OUTLINEFILL  Draws rectangle border and fills

 *) Default value

HRADIUS <nHRad> and VRADIUS <nVRad> determine how much to
round the corners of the rectangle. Both are positive integers
which, taken together, determine the distance (radius of
curvature) from a corner to the middle of the rectangle. This
distance provides the measure from which the corners are
rounded. <nHRad> indicates the horizontal distance. When
<nHRad> is equal to <nVRad> , the corners are rounded by a
90o arc.  <nVRad> determines the vertical curvature radius for
rounding the corners. For rounded corners, both parameters
<nHRad> and <nVRad> must be greater than 0.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

Notes:

The @ DCGRABOX command uses the function GraBox() to draw the box therefore it does not create an object.

CAUTION: Do not use DCGRA* commands with the FIT clause of DCREAD GUI or the AUTORESIZE clause of DCGETOPTIONS, unless the DCGRA* object is drawn on an object that does not get resized or repositioned at a later time. Auto-Sizing and Auto-Fitting is accomplished by traversing child list of the Parent object and reading the size and/or coordinates of all objects. DCGRA* commands are not objects, therefore they cannot be repositioned correctly.

Examples:

#include "dcgra.ch"
LOCAL GetList := {}, GetOptions, i

@ .5,3 DCGRASTRING ;
   {'DCGRA* commands are useful when creating dialogs that require', ;
    'a lot of text, images, lines, boxes or other graphic primitives.', ;
    'These commands automatically handle locking of presentation space', ;
    'and repainting of the graphic area' } ;
   FONT '12.Arial Bold Italic' COLOR GRA_CLR_BLUE ROWSPACE 18

@ 5,4 TO 10,76 DCGRABOX FILL GRA_OUTLINEFILL COLOR GRA_CLR_YELLOW

@ 6.2,15 DCGRAPROC {|o,c,r|_BitMaps(o,c,r)}

FOR i := 1 TO 15
  @ 10.5, i*4 TO 13.5, i*4 DCGRALINE COLOR i
  @ 10.3 + (.22*i),4 TO 10.3 + (.22*i),56 DCGRALINE COLOR i
NEXT

DCGETOPTIONS ;
   WINDOWHEIGHT 400 ;
   WINDOWWIDTH 600

DCREAD GUI ;
   OPTIONS GetOptions ;
   ADDBUTTONS

RETURN nil

/* -------------------- */

STATIC FUNCTION _Bitmaps( oPresSpace, nCol, nRow )

LOCAL aTarget, aSource, oBitMap, nResource, i, nSaveCol

nSaveCol := nCol

FOR nResource := 7110 TO 7119
  oBitMap := XbpBitMap():new():create(oPresSpace)
  oBitMap:load( NIL, nResource )
  aTarget := {nCol,nRow,nCol+oBitmap:xSize,nRow+oBitmap:ySize}
  aSource := {0,0,oBitmap:xSize,oBitmap:ySize}
  nCol += oBitmap:xSize + 5
  IF nResource = 7114
    nRow -= 40
    nCol := nSaveCol
  ENDIF
  oBitmap:draw( oPresSpace, aTarget, aSource, , GRA_BLT_BBO_IGNORE )
  oBitmap:destroy()
NEXT

RETURN nil

Files:

DCGRA.CH

See Also:

   @ DCGRASTRING
   @ DCGRALINE


@ DCGRALINE

Draw a line

The command @..DCGRALINE creates a new GraLine() object and adds the object to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the display/edit mode for all objects found in the GetList array. A Get object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD GUI command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> @..DCGRALINE objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY, @..DCCHECKBOX, @..DCRADIO, @..DCBUTTON or @..DCTABPAGE.

Syntax:

@ <nSRow>,<nSCol> TO <nERow>,<nECol> DCGRALINE ;
    [COLOR <ncFgC>] ;
    [PARENT <oParent>] ;
    [PIXEL]  ;
    [ATTRIBUTE <aAttr>] ;
    [RELATIVE <oRel>] ;
    [TITLE <cTitle>] ;
    [ID <cId>] ;
    [GROUP <cGroup>]                                            ;

Arguments:

<nSRow>, <nSCol>, <nERow>, <nECol> are the row and column of
the screen.  Coordinates are always relative to position 0,0
ie. Top,Left of the parent object, unless the RELATIVE <oRel>
argument is used.  If no parent is assigned, then the parent
is the Dialog box. IF the PIXEL option is set to .TRUE. in
DCGETOPTIONS, then the numbers are in pixels otherwise they
are in standard text-based coordinates.  You can also force
the pixel mode by including PIXEL as a command argument.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.  If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

COLOR <nFGc> is the color of the line to be drawn. It must be
a numeric constant which begin with either the prefix
GRA_CLR_ or the prefix XBPSYSCLR_ as defined in GRA.CH or
XBP.CH.

ID <cId> is a unique identifier for this object.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh(),
DC_PaintGraControls() or DC_ReadGui().

ATTRIBUTE <aAttr> is an array of attributes that meets the
specification for line attributes such as color, mixmode,
line width, line type, etc.

<aAttr> := Array( GRA_AL_COUNT )

<aAttr> is an array whose elements contain the attributes for
character strings drawn by the function GraLine().

#define constants of the attribute array for lines.

These contants are defined in GRA.CH.

#define constants of the attribute array for lines

 Array element   #define group    Default value

 GRA_AL_COLOR    GRA_CLR_*        GRA_CLR_NEUTRAL
 GRA_AL_MIXMODE  GRA_FGMIX_*      GRA_FGMIX_OVERPAINT
 GRA_AL_WIDTH    GRA_LINEWIDTH_*  GRA_LINEWIDTH_NORMAL
 GRA_AL_TYPE     GRA_LINETYPE_*   GRA_LINETYPE_SOLID

Attributes for lines

 Array element   Description

 GRA_AL_COLOR    Foreground color
 GRA_AL_MIXMODE  Color mix attribute for foreground
 GRA_AL_WIDTH    Line width
 GRA_AL_TYPE     Line type

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

Notes:

The @ DCGRALINE command uses the function GraLine() to draw the line therefore it does not create an object.

CAUTION: Do not use DCGRA* commands with the FIT clause of DCREAD GUI or the AUTORESIZE clause of DCGETOPTIONS, unless the DCGRA* object is drawn on an object that does not get resized or repositioned at a later time. Auto-Sizing and Auto-Fitting is accomplished by traversing child list of the Parent object and reading the size and/or coordinates of all objects. DCGRA* commands are not objects, therefore they cannot be repositioned correctly.

Examples:

#include "dcgra.ch"

PROCEDURE Xtest()

LOCAL GetList := {}, GetOptions, i

FOR i := 1 TO 15
  @ 1.5, i*4 TO 4.5, i*4 DCGRALINE COLOR i
  @ 1.3 + (.22*i),4 TO 1.3 + (.22*i),56 DCGRALINE COLOR i
NEXT

DCGETOPTIONS ;
  WINDOWWIDTH 500 ;
  WINDOWHEIGHT 200

DCREAD GUI ADDBUTTONS OPTIONS GetOptions

RETURN

Files:

DCGRA.CH

See Also:

   @ DCGRASTRING
   @ DCGRABOX


@ DCGRAPROC

Draw a screen object with a custom procedure

The command @..DCGRAPROC creates a custom Gra*() object and adds the object to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the display/edit mode for all objects found in the GetList array. A Get object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD GUI command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> @..DCGRAPROC objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY, @..DCCHECKBOX, @..DCRADIO, @..DCBUTTON or @..DCTABPAGE.

Syntax:

@ <nRow>,<nCol>  DCGRAPROC <bProc> ;
   [PARENT <oParent>]              ;
   [PIXEL]                         ;
   [ID <cId>]                      ;
   [GROUP <cGroup>]

Arguments:

<nSRow>, <nSCol> are the row and column coordinates of
the screen.  Coordinates are always relative to position 0,0
ie. Top,Left of the parent object.  If no parent is assigned,
then the parent is the Dialog box. IF the PIXEL option is set
to .TRUE. in DCGETOPTIONS, then the numbers are in pixels
otherwise they are in standard text-based coordinates.  You
can also force the pixel mode by including PIXEL as a command
argument.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.  If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

ID <cId> is a unique identifier for this object.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh(),
DC_PaintGraControls() or DC_ReadGui().

Notes:

CAUTION: Do not use DCGRA* commands with the FIT clause of DCREAD GUI or the AUTORESIZE clause of DCGETOPTIONS, unless the DCGRA* object is drawn on an object that does not get resized or repositioned at a later time. Auto-Sizing and Auto-Fitting is accomplished by traversing child list of the Parent object and reading the size and/or coordinates of all objects. DCGRA* commands are not objects, therefore they cannot be repositioned correctly.

Examples:

#include "dcgra.ch"

LOCAL GetList := {}, GetOptions, i

@ .5,3 DCGRASTRING ;
   {'DCGRA* commands are useful when creating dialogs that require', ;
    'a lot of text, images, lines, boxes or other graphic primitives.', ;
    'These commands automatically handle locking of presentation space', ;
    'and repainting of the graphic area' } ;
    FONT '12.Arial Bold Italic' COLOR GRA_CLR_BLUE ROWSPACE 18

@ 5,4 TO 10,76 DCGRABOX FILL GRA_OUTLINEFILL COLOR GRA_CLR_YELLOW

@ 6.2,15 DCGRAPROC {|o,c,r|_BitMaps(o,c,r)}

FOR i := 1 TO 15
  @ 10.5, i*4 TO 13.5, i*4 DCGRALINE COLOR i
  @ 10.3 + (.22*i),4 TO 10.3 + (.22*i),56 DCGRALINE COLOR i
NEXT

DCGETOPTIONS ;
   WINDOWHEIGHT 400 ;
   WINDOWWIDTH 600

DCREAD GUI ;
   OPTIONS GetOptions ;
   ADDBUTTONS

RETURN nil

/* -------------------- */

STATIC FUNCTION _Bitmaps( oPresSpace, nCol, nRow )

LOCAL aTarget, aSource, oBitMap, nResource, i, nSaveCol

nSaveCol := nCol

FOR nResource := 7110 TO 7119
  oBitMap := XbpBitMap():new():create(oPresSpace)
  oBitMap:load( NIL, nResource )
  aTarget := {nCol,nRow,nCol+oBitmap:xSize,nRow+oBitmap:ySize}
  aSource := {0,0,oBitmap:xSize,oBitmap:ySize}
  nCol += oBitmap:xSize + 5
  IF nResource = 7114
    nRow -= 40
    nCol := nSaveCol
  ENDIF
  oBitmap:draw( oPresSpace, aTarget, aSource, , GRA_BLT_BBO_IGNORE )
  oBitmap:destroy()
NEXT

RETURN nil

Files:

DCGRA.CH

See Also:

   @ DCGRASTRING
   @ DCGRALINE


@ DCGRASTRING

Write a text string

The command @..DCGRASTRING creates a new GraStringAt() object and adds the object to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the display/edit mode for all objects found in the GetList array. A Get object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD GUI command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> @..DCGRASTRING works similarly to the @..DCSAY command except that it uses the Xbase++ GraStringAt() function rather than an XbpStatic() object. It is recommended that this command be used in place of @..DCSAY when there is a lot of text to write to a GUI screen as it uses far less memory resources and paints faster.<br><br> @..DCGRASTRING objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY, @..DCCHECKBOX, @..DCRADIO, @..DCBUTTON or @..DCTABPAGE.

Syntax:

@ <nSayRow>,<nSayCol> DCGRASTRING <abcText> ;
    [COLOR <nFgC>,[<nBgC>] ] ;
    [FONT <bocFont>] ;
    [PARENT <oParent>] ;
    [PICTURE <cPict>] ;
    [PIXEL] ;
    [ATTRIBUTE <aAttr>] ;
    [RELATIVE <oRel>] ;
    [ID <cId>] ;
    [TITLE <cTitle>] ;
    [GROUP <cGroup>]

Arguments:

<nSayRow> and <nSayCol> are the row and column of the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE <oRel> argument is
used.  If no parent is assigned, then the parent is the Dialog
box. IF the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel
mode by including PIXEL as a command argument.

<abcText> is the text to display. This may be a character string,
an array of character string or a code-block which returns a
character string or array of character strings.
of any type except an object or array. It must not be a macro.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

FONT <cFont> is a character string defining an optional font
for the text.  The font string must conform to the Xbase++
standard, ie. "10.Courier Bold. It may also be a font object or
a code block that returns a character string or a font object
to later refresh with DC_GraPaintControls().

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.  If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

PICTURE <cPict> is a character string specifying formatting
options for the value of <VarName> during display and editing.

COLOR <nFGc>, <nBGc> are foreground and background colors for
the text.  They must be numeric constants which begin with
either the prefix GRA_CLR_ or the prefix XBPSYSCLR_ as defined
in GRA.CH or XBP.CH.

ID <cId> is a unique identifier for this object.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh(),
DC_PaintGraControls() or DC_ReadGui().

ATTRIBUTE <aAttr> is an array of attributes that meets the
specification for string attributes such as color, mixmode,
alignment, etc.

<aAttr> := Array( GRA_AS_COUNT )

<aAttr> is an array whose elements contain the attributes for
character strings drawn by the function GraStringAt().

#define constants of the attribute array for character strings.

These contants are defined in GRA.CH.

 Array element       #define | value     Default value

 GRA_AS_COLOR        GRA_CLR_*           GRA_CLR_NEUTRAL
 GRA_AS_BACKCOLOR    GRA_CLR_*           GRA_CLR_BACKGROUND
 GRA_AS_MIXMODE      GRA_FGMIX_*         GRA_FGMIX_OVERPAINT
 GRA_AS_BGMIXMODE    GRA_BGMIX_*         GRA_BGMIX_LEAVEALONE
 GRA_AS_BOX          { nXsize, nYsize }  dependent on output device
 GRA_AS_ANGLE        { nX, nY }          { 1, 0 }
 GRA_AS_SHEAR        { nX, nY }          { 0, 1 }

 GRA_AS_DIRECTION    GRA_CHDIRN_*        GRA_CHDIRN_LEFTRIGHT
 GRA_AS_HORIZALIGN   GRA_HALIGN_*        GRA_HALIGN_LEFT
 GRA_AS_VERTALIGN    GRA_VALIGN_*        GRA_VALIGN_BASE
 GRA_AS_EXTRA        nExtra              0
 GRA_AS_BREAK_EXTRA  nBreakExtra         0

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

Notes:

The @ DCGRASTRING command uses the function GraStringAt() to draw the text therefore it does not create an object.

CAUTION: Do not use DCGRA* commands with the FIT clause of DCREAD GUI or the AUTORESIZE clause of DCGETOPTIONS, unless the DCGRA* object is drawn on an object that does not get resized or repositioned at a later time. Auto-Sizing and Auto-Fitting is accomplished by traversing child list of the Parent object and reading the size and/or coordinates of all objects. DCGRA* commands are not objects, therefore they cannot be repositioned correctly.

Examples:

#include "dcgra.ch"

PROCEDURE Xtest()

LOCAL GetList := {}, cLastName := Space(15), cFirstName := Space(15),;
      cCompany := Space(25), cStreet := Space(25), cCity := Space(25),;
      cState := Space(2), cCountry := Space(20), cPhone := Space(15),;
      GetOptions

@ 5,10 DCGRASTRING ;
  { 'Last Name', ;
    'First Name', ;
    'Company', ;
    'Street', ;
    'City', ;
    'State', ;
    'Country', ;
    'Phone' }

@ 5,25 DCGET cLastName
@ 6,25 DCGET cFirstName
@ 7,25 DCGET cCompany
@ 8,25 DCGET cStreet
@ 9,25 DCGET cCity
@10,25 DCGET cState
@11,25 DCGET cCountry
@12,25 DCGET cPhone PICT '(999)-999-9999'

DCREAD GUI ;
    FIT ;
    ADDBUTTONS ;

RETURN

Files:

DCGRA.CH

See Also:

   @ DCSAY GET


@ DCGROUP

Create a GROUP object for displaying with GUI reader

The command @..DCGROUP creates a new Group object and adds the object to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> A "Group" object is used to group other objects together, for example, Radio-Buttons must be part of a group to function properly as a set. A "Group" object is also used to draw a box around a set of objects and provide a means to reference all the objects to the home position 0,0 of the group.<br><br> @..DCGROUP objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCRADIO, @..DCPUSHBUTTON or @..DCMULTILINE.<br><br>

Syntax:

@ <nSRow>,<nSCol> DCGROUP <oGroup> ;
    [BOX <cBox>] ;
    [SIZE <nWidth>, <nHeight>] ;
    [PARENT <oParent>] ;
    [PARENTID <cParentId>] ;
    [CAPTION <cText>] ;
    [WHEN <bWhen>] ;
    [HIDE <bHide>] ;
    [FONT <bocFont>] ;
    [MESSAGE <bcMsg> [INTO <oMsgBox>]] ;
    [COLOR <bncFgC> [,<ncBgC>] ] ;
    [HELPCODE <cHelpCode>] ;
    [PRESENTATION <aPres>] ;
    [PIXEL] ;
    [TOOLTIP <bcToolTip>] ;
    [CURSOR <naCursor>] ;
    [CARGO <xCargo>] ;
    [PREEVAL <bPreEval>] ;
    [EVAL <bEval>] ;
    [RELATIVE <oRel>] ;
    [ID <cId>] ;
    [TITLE <cTitle>] ;
    [ACCELKEY <anAccel>] ;
    [GOTFOCUS <bGotFocus>] ;
    [LOSTFOCUS <bLostFocus>] ;
    [TABSTOP]  ;
    [NOTABSTOP];
    [TABGROUP <nTabGroup>] ;
    [GROUP <cGroup>] ;
    [VISIBLE] ;
    [INVISIBLE] ;
    [RESIZE <aResize> [SCALEFONT] ] ;
    [DRAG <bDrag> [DIALOG <bDD>] ;
    [DROP <bDrop> [CURSOR <nDropCursor>] ;
    [SUBCLASS <cSubClass>]

Arguments:

<nSRow>, <nSCol> are the coordinates on the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE argument is used.
If no parent is assigned, then the parent is the Dialog box.

<oGroup> is the name of the variable to assign as a storage
place for this object.

BOX <cBox> is used only in text mode.  <cBox> is a character
string of eight characters defining the box used for the
group.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

IF the PIXEL option is set to .TRUE. in DCGETOPTIONS, then
the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel
mode by including PIXEL as a command argument.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.
The object is passed as a parameter to the code block.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the object will be disabled and grayed.
If the value returned is .TRUE. then the object will be enabled.
The object is passed as a parameter to the code block.

SIZE <nWidth>, <nHeight> defines the size of the group.
If no size is given, then the group will be automatically
sized to fit the parent window.  IF the PIXEL option is set to
.TRUE. in DCGETOPTIONS, then the numbers are in pixels,
otherwise they are in standard text-based coordinates.  You
can also force the pixel mode by including PIXEL in the command.

CAPTION <cCaption> is the caption to place on the group.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.  If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

MESSAGE <bcMsg> is the message you want to display in the
message area of the dialogue screen defined by the DCMESSAGEBOX
command when the object is in focus.  Optionally, INTO <oMsgBox>
will designate which message box to display the message into.
If the INTO clause is not used, then the last message box in the
GetList is the default. <oMsgBox> may also be any object that
supports the :setCaption() method.  If <bcMsg> is a code-block,
it must return a character string.

FONT <cFont> is a character string defining an optional font.
The font string must conform to the Xbase++ standard, ie.
"10.Courier Bold". It may also be a font object or a code block
that returns a character string or a font object to later
refresh with DC_GetRefresh().

HELPCODE <cHelp> is a character string that is passed to the
DC_HelpF1() function if F1 is pressed when the mouse is placed
over any area of the Group that does not contain an object.
The help code is used by the Help system to override the
passing of the Procedure and Varname for more specific
context-help.

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the Group object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.

TOOLTIP <bcToolTip> is a character string which will display
as a "Tool Tip" next to the object when the cursor is passed
over the object. A semi-colon within the text indicates a new
line.  If <bcToolTip> is a code-block, it must return a character
string.  NOTE: The Tooltip painting method is run in another
thread, therefore the codeblock should not run code that points
to the current work area.  It may however, contain local, public
or private variables.

CURSOR <naCursor> may be either a numeric value or an array of
3 elements which defines an optional mouse pointer to use for
this object.  System mouse pointers start with
XBPWINDOW_POINTERTYPE_ and are defined in XPB.CH.  The default
pointer is XBPWINDOW_POINTERTYPE_POINTER.  <naCursor> may be a
numeric resource ID that points to a Bit-Map that has been
compiled with the resource compiler and linked to the .EXE.
<naCursor> may be a 3-element array described as follows:

  Element  Type  Description
  -------  ---- ---------------------------------------------
    [1]      C   Optional name of .DLL containing the pointer
                 resource.

    [2]      N   The numeric resource ID of the pointer.  If
                 element 1 is a NIL, then this resource must be
                 linked into the .EXE.

    [3]      N   The type of resource as defined in XBP.CH.

COLOR <ncFGc>, <ncBGc> are foreground and background colors.
They may be character strings representing valid text-based
colors supported by SetColor() or they may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH. If <bncFGc> is a
code block is must return a 2-element array containing a
foreground and background color.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

ACCELKEY <anAccel> is a numeric "hot-key" assignment that will set
focus to the checkbox object when the hot-key is pressed.  The key
must be a valid key with the prefix xbeK_*.  These keys are
defined in APPEVENT.CH.  <anAccel> may also be an array of numeric
values to assign more than one key to the object.

GOTFOCUS <bGotFocus> is a code block that is evaluated when this
object receives input focus.  <bGotFocus> := {|uNIL1,uNIL2,self|...}

LOSTFOCUS <bLostFocus> is a code block that is evaluated when this
object loses input focus.  <bLostFocus> := {|uNIL1,uNIL2,self|...}

TABSTOP will cause the object (Xbase Part) to be set when using
the Tab key.  Note: When logical groups are defined in a dialog
using TABGROUP <nTabGroup>, TABSTOP is usually set to .T. (true)
for the first dialog element in the group.  This allows the first
dialog element of a group to be activated using the Tab key.

NOTABSTOP will cause the object (Xbase Part) to be ignored when
using the Tab key. This clause is needed only to override any
default setting of TabStop by the DCGETOPTIONS [TABSTOP] command.

TABGROUP <nTabGroup> allows objects (Xbase Parts) that are created
immediately after one another in the GetList to be combined into
logical groups. This allows the user to navigate within a dialog
from group to group by pressing the Tab key.  Within a group of
dialog elements navigation is performed using the cursor keys.

Only constants defined in the XBP.CH file can be used as values
for this instance variable.  The following table lists the
available constants:

#define constants for <nTabGroup>:

 Constant             Description

 XBP_NO_GROUP     *)  Dialog element does not belong to a group
 XBP_BEGIN_GROUP      Dialog element is the first in a group
                      (this begins the definition of the group)
 XBP_WITHIN_GROUP     Dialog element is within a group
 XBP_END_GROUP        Dialog element is the last in a group
                      (this ends the definition of the group)

*) Default value

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS

RESIZE <aResize> is an optional array of two (2) elements
used for resizing and repositioning the object when the parent
is resized.

NOTE: RESIZE is to be used in conjunction with the RESIZE clause
      of DCGETOPTIONS. See the RESIZE clause of DCGETOPTIONS for
      examples.

      The optional SCALEFONT clause will automatically scale the
      font size up or down when the object is resized.

DRAG <bDrag> is a codeblock to evaluate when the left mouse button
is clicked in the object and the drag is started.  The return
value of the code block will be stored in memory to be later
retrieved by the Drop operation. A pointer to the clicked on
object is passed to the code block.

DIALOG <bDD> is a codeblock that will evaluate when the drag is
started.  This is used to call a function that will create a
dialog window which will move with the mouse during the drag.
The dialog window will be destroyed upon the drop operation
or the release of the mouse.

Ex: DRAG {|o|o:getData()} DIALOG {|mp1,mp2,oXbp|DragDialog(mp1,mp2,oXbp)} ;

DROP <bDrop> is a codeblock to evaluate when the left mouse button
is released in the object and the drag is ended.  A pointer to
the object and the value stored in memory at the start of the
Drag are passed to the code block.

CURSOR <nDropCursor> is the mouse cursor that will show when it
is moved over this object during a drag operation.

Ex: DROP {|o,x|o:setData(x),o:invalidateRect()} ;
       CURSOR CURSOR POINTER_DATADROP_ASSIGN

SUBCLASS <cSubClass> is a string containing a class name that
will be used to create the class, rather than DC_XbpStatic().
This class should inherit from DC_XbpStatic().
See the example in \exp19\samples\subclass.

Notes:

The group object created by @ DCGROUP is an object of the XbpStatic() class, therefore it can be manipulated with any iVar or method supported by XbpStatic().

Examples:

  #include "dcdialog.ch"

  PROCEDURE Xtest()

  LOCAL GetList := {}, GetOptions, cOption, oMyGroup

  cOption := 'P'

  @ 4,10 DCGROUP oMyGroup CAPTION "Select an Operation" ;
    SIZE 40,8

  @ 1,2 DCRADIO cOption PROMPT 'Save to Dictionary' VALUE 'D' ;
        PARENT oMyGroup

  @ 2,2 DCRADIO cOption PROMPT 'Save to Source Code' VALUE 'S' ;
        PARENT oMyGroup

  @ 3,2 DCRADIO cOption PROMPT 'Make a Backup file' VALUE 'B' ;
        PARENT oMyGroup

  @ 4,2 DCRADIO cOption PROMPT 'Pack the File' VALUE 'P' ;
        PARENT oMyGroup

  DCREAD GUI ;
    TITLE 'My Dialogue' ;
    FIT ;
    ADDBUTTONS

  RETURN

Files:

DCDIALOG.CH


@ DCHTMLVIEWER

Create a Web Browser object for displaying with GUI reader

The command @..DCHTMLVIEWER creates a WebBrowser object and adds the object to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> @..DCHTMLVIEWER objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCRADIO, @..DCPUSHBUTTON or @..DCMULTILINE.<br><br>

Syntax:

@ <nRow>,<nCol> DCHTMLVIEWER <oObject> ;
    [SIZE <nWidth>, <nHeight>] ;
    [PARENT <oParent>] ;
    [PARENTID <cParentId>] ;
    [CARGO <xCargo>] ;
    [HIDE <bHide>] ;
    [PRESENTATION <aPres>] ;
    [PIXEL] ;
    [PREEVAL <bPreEval>] ;
    [POSTEVAL <bPostEval>] ;
    [RELATIVE <oRel>] ;
    [ID <cId>] ;
    [TITLE <cTitle>] ;
    [TABSTOP]  ;
    [NOTABSTOP];
    [TABGROUP <nTabGroup>] ;
    [VISIBLE] ;
    [INVISIBLE] ;
    [GROUP <cGroup>] ;
    [RESIZE <aResize>] ;
    [NAVIGATE <url>] ;
    [SETHTML <html>] ;
    [BEFORENAVIGATE <bBeforeNav>] ;
    [DOCCOMPLETE <bDocComplete>] ;
    [NAVCOMPLETE <bNavComplete>] ;
    [STATUSTEXTCHANGE <bStatChange>] ;
    [PROGRESSCHANGE <cProgChange>] ;
    [TITLECHANGE <bTitleChange>] ;
    [SUBCLASS <cSubClass>]
                                ;

Arguments:

<nRow>, <nCol> are the coordinates on the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE <oRel> argument is
used.  If no parent is assigned, then the parent is the Dialog
box.  IF the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel
mode by including PIXEL as a command argument.

OBJECT <oObject> is the name of the variable to assign as a
storage place for this object.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

SIZE <nWidth>, <nHeight> defines the size of the object.
If no size is given, then the object will be automatically
sized to fit the caption.  IF the PIXEL option is set to .TRUE.
in DCGETOPTIONS, then the numbers are in pixels otherwise they
are in standard text-based coordinates.  You can also force the
pixel mode by including PIXEL in the command.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object. If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the Static object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

POSTEVAL <bPostEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.
The object is passed as a parameter to the code block.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS

RESIZE <aResize> is an optional array of two (2) elements
used for resizing and repositioning the object when the parent
is resized.

NOTE: RESIZE is to be used in conjunction with the RESIZE clause
      of DCGETOPTIONS. See the RESIZE clause of DCGETOPTIONS for
      examples.

NAVIGATE <url> is a character string with the URL or document to
navigate to. This parameter may be specified as an URL,
full-qualified path or an Universal Naming Convention (UNC)
location and resource name.

SETHTML <html> is an HTML-formatted string to the internal buffer
of an XbpHTMLViewer object.

BEFORENAVIGATE <bBeforeNav> is a callback that is generated when the
XbpHTMLViewer object is about to navigate to a new HTML page or
document. The method :beforeNavigate() returns a logical value
that specifies whether navigation is allowed to commence. To
prevent navigation from occuring, the application must return
the value .F. (FALSE).

DOCCOMPLETE <bDocComplete> is a callback that is generated when
the XbpHTMLObject has finished loading a document.

NAVCOMPLETE <bNavComplete> is a callback that is generated when
the XbpHTMLObject has finished navigating to a link or document.
Note: The xbeHTML_BeforeNavigate notification is a synchronous
event. It is sent directly to the application via the XbpHTMLViewer
object's :handleEvent() method. The xbeHTML_BeforeNavigate event
code is not normally returned by the function AppEvent().

STATUSTEXTCHANGE <bStatChange> is a callback that is generated
whenever the status of the XbpHTMLViewer object changes. When a
document is loaded, for example, the object uses the
xbeHTML_StatusTextChange notification to send continous status
information, which the application may use for display in its
status bar.

PROGRESSCHANGE <cProgChange> is a callback that informs the
application about a change in progress of the current operation.
When a document is loaded, the object uses the
xbeHTML_ProgressChange notification to inform the application
about the progress made.

TITLECHANGE <bTitleChange> is a callback that is generated when
the title of the document displayed changes or becomes first
available.

SUBCLASS <cSubClass> is a string containing a class name that
will be used to create the class, rather than DC_XbpHtmlViewer().
This class should inherit from DC_XbpHtmlViewer().
See the example in \exp19\samples\subclass.

Notes:

The object created by @ DCHTMLVIEWER is an object of the XbpHTMLViewer() class, therefore it can be manipulated with any iVar or method supported by XbpHTMLViewer().

Examples:

See the example in SAMPLES\ACTIVEX\WEBBROW.PRG.

Files:

DCDIALOG.CH

See Also:

   @ DCACTIVEXCONTROL


@ DCKLMLE

Create a MULTILINE edit for displaying with GUI reader

The command @..DCKLMLE creates a new multi-line edit object and adds the object to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released.<br><br> @..DCKLMLE objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCRADIO, @..DCBUTTON, @..DCCHECKBOX or @..DCTABPAGE.<br><br>

Syntax:

@ <nRow>,<nCol> DCKLMLE <uVar> ;
    [PARENT <oParent>] ;
    [VALID <bValid>] ;
    [WHEN <bWhen>] ;
    [HIDE <bHide>] ;
    [EDITPROTECT <bProtect>] ;
    [SIZE <nWidth>,<nHeight>] ;
    [MESSAGE <bcMsg> [INTO <oMsgBox>]] ;
    [FONT <cFont>] ;
    [COLOR <bncFgC> [,<ncBgC>] ] ;
    [HELPCODE <cHelpCode>] ;
    [DATALINK <bLink>] ;
    [OBJECT <oObject>] ;
    [CARGO <xCargo>] ;
    [READONLY] ;
    [NOWORDWRAP] ;
    [NOBORDER] ;
    [NOVERTSCROLL] ;
    [NOHORIZSCROLL] ;
    [IGNORETAB] ;
    [COMPATIBLE] ;
    [PRESENTATION <aPres>] ;
    [PIXEL] ;
    [TOOLTIP <bcToolTip>] ;
    [CURSOR <naCursor>] ;
    [PREEVAL <bPreEval>] ;
    [EVAL <bEval>] ;
    [RELATIVE <oRel>] ;
    [ID <cId>] ;
    [TITLE <cTitle>] ;
    [ACCELKEY <nKey>] ;
    [GOTFOCUS <bGotFocus>] ;
    [LOSTFOCUS <bLostFocus>] ;
    [TABSTOP] ;
    [NOTABSTOP] ;
    [TABGROUP <nTabGroup>] ;
    [VISIBLE] ;
    [INVISIBLE] ;
    [GROUP <cGroup>] ;
    [EXITKEY <nExitKey>] ;
    [MAXLINES <nMaxLines> [MESSAGE <bcMaxLinesMessage>]] ;
    [LINELENGTH <nLineLength> [MESSAGE <bcLineLengthMessage>]] ;
    [MAXCHARS <nMaxChars> [MESSAGE <bcMaxCharsMessage>]] ;

    [MAINDICT <cMainDict>] ;
    [ADDONDICT <cAddOnDict>] ;
    [SUGGESTFONT <cSuggestFont>] ;
    [ABOXPOS <aBoxPos>] ;
    [SHORTSPELL <nShortSpell>] ;
    [DELWORDKEY <nDelWordKey>] ;
    [DELWORDFUN <nDelWordFun>] ;
    [DELLINEKEY <nDelLineKey>] ;
    [DELLINEFUN <nDelLineFun>] ;
    [PRINTFONT <cPrtFont>] ;
    [TOPMARGIN <nPrtTopMar>] ;
    [LEFTMARGIN <nPrtLeftMar>] ;
    [BOTTOMMARGIN <nPrtBotMar>] ;
    [WORDDELIMITERS <cWrdDelimit>] ;
    [FINDHIGHLIGHT] ;
    [MATCHCASE] ;
    [REMEMBERFIND] ;
    [NOREMEMBERFIND] ;
    [SEARCHWRAP] ;
    [NOSEARCHWRAP] ;
    [FINDBOXPOS <aFindBoxPos>]

Arguments:

<nRow> and <nCol> are the row and column of the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE <oRel> argument is
used.  If no parent is assigned, then the parent is the Dialog
box.  IF the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel
mode by including PIXEL as a command argument.

<uVar> is the input/output variable.  This should be
initialized to a character string. It must not be a macro, however
it may be a code block that contains a macro. The <uVar> is
automatically anchored via a Get-Set codeblock created by
DC_GetAnchorCB() unless <uVar> is a custom Get-Set
code block.

RELATIVE<oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

SIZE <nWidth>,<nHeight> is the width and height of the
multiline box.  If the PIXEL option is set to .TRUE. in DCGET
OPTIONS, then the numbers are in pixels otherwise they are
in standard text-based numbers.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.  If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

OBJECT <oObject> is the name of the variable to assign as a
storage place for this object.

FONT <cFont> is a character string defining an optional font.
The font string must conform to the Xbase++ standard, ie.
"10.Courier Bold".

MESSAGE <bcMsg> is the message you want to display in the
message area of the dialogue screen defined by the DCMESSAGEBOX
command when the object is in focus.  Optionally, INTO <oMsgBox>
will designate which message box to display the message into.
If the INTO clause is not used, then the last message box in the
GetList is the default. <oMsgBox> may also be any object that
supports the :setCaption() method.If <bcMsg> is a code-block,
it must return a character string.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the object will be disabled and grayed.
If the value returned is .TRUE. then the object will be enabled.
The object is passed as a parameter to the code block.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.
The object is passed as a parameter to the code block.

EDITPROTECT <bProtect> is an optional condition tested during the
execution of the GUI gets by the DCREAD GUI command, before the
object receives input focus (before it is activated). When the
condition returns the value .T. (true), the object receives the
input focus.  Otherwise, it is skipped. <bProtect> is a code
block that must return a logical value when evaluated. The code
block is evaluated prior to the object receiving input focus.
This clause behaves similar to the WHEN clause with the exception
that the object is not disabled (grayed out).  The object is
passed as a parameter to the code block.

VALID <bValid> is an optional condition tested during the
execution of the GUI gets by the READ command before an
object loses input focus (before it is deactivated).  When
the condition returns the value .T. (true), the object
loses the input focus.  Otherwise, it remains active. <bValid>
is a code block that must return a logical value when it is
evaluated.  The object passed as a parameter to the code block.

HELPCODE <cHelp> is a character string that is passed to the
DC_HelpF1() function if F1 is pressed or the HELP button
is clicked when this object has focus.  This HELPCODE allows
the Help system to override the passing of the Procedure and
Varname for more specific context-help.

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the multiline object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.

READONLY will not allow editing of the text.  The entire text
area will be grayed.

NOWORDWRAP means that the text is not wrapped.  The default is
word-wrap ON so that it is completely displayed in the edit
window.  Individual text lines that contain more characters
than can be displayed within the edit window are automatically
wrapped at the spaces between words.  With NOWORDWRAP, new
lines are started in the edit window only when CRLF explicitly
appears in the edit buffer. Text lines that contain more
characters than can be displayed in the edit window are cut
off and the text must be horizontally scrolled in order to view
all the characters.  To enable WORDWRAP the NOHORIZSCROLL clause
must be used.

NOVERTSCROLL will suppress the vertical scrollbar on the right
side of the window.

NOHORIZSCROLLwill suppress the horizontal scrollbar on the
bottom of the window.

IGNORETAB causes the Tab key to navigates between other objects
on the dialog screen and is not interpreted as a character.
The default action is for the Tab key character to be written
to the edit buffer.

NOBORDER suppress the painting of a border around the object.

COMPATIBLE will make navigation keys compatabile with those of
MemoEdit().  This means that keys like CTRL-R, CTRL-C, CRTL-E,
CRTL-X, CTRL-Y, etc. will be recognized in addition to all the
standard "windows-compatabile" keys.

TOOLTIP <bcToolTip> is a character string which will display
as a "Tool Tip" next to the object when the cursor is passed
over the object. A semi-colon within the text indicates a new
line.  If <bcToolTip> is a code-block, it must return a character
string.  NOTE: The Tooltip painting method is run in another
thread, therefore the codeblock should not run code that points
to the current work area.  It may however, contain local, public
or private variables.

CURSOR <naCursor> may be either a numeric value or an array of
3 elements which defines an optional mouse pointer to use for
this object.  System mouse pointers start with
XBPWINDOW_POINTERTYPE_ and are defined in XPB.CH.  The default
pointer is XBPWINDOW_POINTERTYPE_POINTER.  <naCursor> may be a
numeric resource ID that points to a Bit-Map that has been
compiled with the resource compiler and linked to the .EXE.
<naCursor> may be a 3-element array described as follows:

  Element  Type  Description
  -------  ---- ---------------------------------------------
    [1]      C   Optional name of .DLL containing the pointer
                 resource.

    [2]      N   The numeric resource ID of the pointer.  If
                 element 1 is a NIL, then this resource must be
                 linked into the .EXE.

    [3]      N   The type of resource as defined in XBP.CH.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

COLOR <ncFGc>, <ncBGc> are foreground and background colors.
They may be character strings representing valid text-based
colors supported by SetColor() or they may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH. If <bncFGc> is a
code block is must return a 2-element array containing a
foreground and background color.

ID<cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

DATALINK <bLink> is an optional code block that is evaluated
every time Get/Set codeblock is evaluated, ie when the data
is read from the <uVar> into the object.  <bLink> is also
evaluated when DC_GetRefresh() is called unless the <lDataLink>
parameter of DC_GetRefresh() is .FALSE.

ACCELKEY <nKey> is a numeric "hot-key" assignment that will set
focus to the memo object when the hot-key is pressed.  The key
must be a valid key with the prefix xbeK_*.  These keys are
defined in APPEVENT.CH.

GOTFOCUS <bGotFocus> is a code block that is evaluated when this
object receives input focus.  <bGotFocus> := {|uNIL1,uNIL2,self|...}

LOSTFOCUS <bLostFocus> is a code block that is evaluated when this
object loses input focus.  <bLostFocus> := {|uNIL1,uNIL2,self|...}

TABSTOP will cause the object (Xbase Part) to be set when using
the Tab key.  Note: When logical groups are defined in a dialog
using TABGROUP <nTabGroup>, TABSTOP is usually set to .T. (true)
for the first dialog element in the group.  This allows the first
dialog element of a group to be activated using the Tab key.

NOTABSTOP will cause the object (Xbase Part) to be ignored when
using the Tab key. This clause is needed only to override any
default setting of TabStop by the DCGETOPTIONS [TABSTOP] command.

TABGROUP<nTabGroup> allows objects (Xbase Parts) that are created
immediately after one another in the GetList to be combined into
logical groups. This allows the user to navigate within a dialog
from group to group by pressing the Tab key.  Within a group of
dialog elements navigation is performed using the cursor keys.

Only constants defined in the XBP.CH file can be used as values
for this instance variable.  The following table lists the
available constants:

#define constants for <nTabGroup>:

 Constant             Description

 XBP_NO_GROUP     *)  Dialog element does not belong to a group
 XBP_BEGIN_GROUP      Dialog element is the first in a group
                      (this begins the definition of the group)
 XBP_WITHIN_GROUP     Dialog element is within a group
 XBP_END_GROUP        Dialog element is the last in a group
                      (this ends the definition of the group)

*) Default value

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().
VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS.

EXITKEY <nExitKey> defines a key to be used to move focus from
the MULTILINE object to the next GET or MULTILINE object in the
GetList.

MAXLINES <nMaxLines> is the maximum number of lines which may be
entered.  If the MESSAGE <bcMaxLinesMessage> clause is used, then
the message will also be displayed when the number of lines is
exceeded.

LINELENGTH <nLineLength> is the maximum number of characters allowed
on a line. If the MESSAGE <bcLineLengthMessage> clause is used, then
the message will also be displayed when a line exceeds the
designated length.

MAXCHARS <nMaxChars> is the maximum number of characters which may
be entered.  If the MESSAGE <bcMaxCharsMessage> clause is used, then
the message will also be displayed when the number of characters
is exceeded.

MAINDICT <cMainDict> Path & file name of main dictionary (KL_Spell.dic)

ADDONDICT <cAddOnDict> Path & file name of add on dictionary (Added.dic)

SUGGESTFONT <cSuggestFont> CompoundName Font for suggestion box (Depends
         on screen resolution)

ABOXPOS <aBoxPos> Position array for starting position of suggestion box
         relative to AppDeskTop() (Default position calculated)

SHORTSPELL <nShortSpell> Shortcut key to start spell check (xbeK_CTRL_Q)

DELWORDKEY <nDelWordKey> Key for delete word (xbeK_CTRL_BS)

DELWORDFUN <nDelWordFun> Function Key for delete word (xbeK_F8)

DELLINEKEY <nDelLineKey> Key for delete line (xbeK_ALT_K)

DELLINEFUN <nDelLineFun> Function Key for delete line (xbeK_F7)

PRINTFONT <cPrtFont> Default Compound Font name for printing

TOPMARGIN <nPrtTopMar> Default top margin for printing

LEFTMARGIN <nPrtLeftMar> Default left margin for printing

BOTTOMMARGIN <nPrtBotMar> Default bottom margin for printing

WORDDELIMITERS <cWrdDelimit> String of all characters which delimit
        words for find operations.

FINDHIGHLIGHT Default to highlight found word.

MATCHCASE Forces find operations to be case sensitive.

REMEMBERFIND Logical option to cause KL_MLE to remember the find string for the
        next search operation.

NOREMEMBERFIND Logical option to cause KL_MLE to start each find operation with
        a blank string.

SEARCHWRAP Option to force KL_MLE to wrap back to top of the string at the end
        of a search.  (not yet functional)

NOSEARCHWRAP Option to cause KL_MLE to stop searching at the end of the string,
        without wrapping (this is the default)

FINDBOXPOS <aFindBoxPos> Position array for starting position of find/replace box
         relative to AppDeskTop() (Default position calculated)

Notes:

DCKLMLE is a special 3rd party class that accesses KL_MLE. KL_MLE is available from Informed Computer Solutions, Inc. for further information on ordering KL_MLE, contact:

Ken Levit -> KL_MLE@VetsPet.com

The multiline object created by @ DCKLMLE is an object of the XbpMLE() class, therefore it can be manipulated with any iVar or method supported by XbpMLE(). In addition the DCKLMLE supports the following special methods: (Refer to KL_MLE documentation for details on these methods and shortcut keys available in KL_MLE.

DeHighlight() GoTop() RowHeight() DeleteLine() isOnScreen() RowsOnScreen() DeleteWord() LineCount() ScrollToCursor() Find() Print() SetTabs() GetLine() ReplaceAllFind() SelectAll() GoBottom() ReplaceLastFind() SpellCheck()

Examples:

  #include "dcdialog.ch"
  #include "dc3p.ch"

  PROCEDURE Xtest()
  LOCAL GetList := {}, cMemo, lOk

  USE COLLECT NEW SHARED

  cMemo := COLLECT->memo

  @ 0,0 DCMULTILINE cMemo FONT "10.Courier" SIZE 80,10
  @ 1,1 DCKLMLE cMemo                    ;
             NOHORIZSCROLL               ;
             SIZE 77.5,9.5               ;
             FONT "10.Courier"           ;
             GROUP "NoteField"           ;
             ID "TheNote"                ;
             SUGGESTFONT "10.Arial Bold" ;
             MAINDICT "Test.Dic"         ;
             ADDONDICT "TestAdd.Dic"     ;
             PRINTFONT "10.Courier New"  ;
             OBJECT oNote

  DCREAD GUI ;
     FIT ;
     ADDBUTTONS TO lOk

  IF lOk .AND. DC_RecLock()
    REPL COLLECT->memo WITH cMemo
    UNLOCK
  ENDIF

  CLOSE collect

  RETURN

Files:

DC3P.CH

See Also:

   @ DCMULTILINE


@ DCLISTBOX

Create a LISTBOX object for displaying with GUI reader

The command @..DCLISTBOX creates a new List Box object and adds the object to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> @..DCLISTBOX objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCRADIO, @..DCPUSHBUTTON, @..DCCHECKBOX or @..DCTABPAGE.<br><br>

Syntax:

@ <nRow>,<nCol> DCLISTBOX <uOutVar> LIST <aVar> ;
    [PARENT <oParent>] ;
    [PARENTID <cParentId>] ;
    [SIZE <nWidth>,<nHeight>] ;
    [WHEN <bWhen>] ;
    [HIDE <bHide>] ;
    [EDITPROTECT <bProtect>] ;
    [FONT <bocFont>] ;
    [PRESENTATION <aPres>] ;
    [HORIZSCROLL] ;
    [MARKMODE <nMarkMode>] ;
    [SELECT <aSelect>] ;
    [PIXEL] ;
    [TOOLTIP <bcToolTip>] ;
    [MESSAGE <bcMsg> [INTO <oMsgBox>]] ;
    [DATALINK <bLink>] ;
    [ITEMMARKED <bItemMarked>] ;
    [ITEMSELECTED <bItemSelected>] ;
    [COLOR <bncFgC> [,<ncBgC>] ] ;
    [OBJECT <oObject>] ;
    [CARGO <xCargo>] ;
    [CURSOR <naCursor>] ;
    [PREEVAL <bPreEval>] ;
    [EVAL <bEval>] ;
    [RELATIVE <oRel>] ;
    [ID <cId>] ;
    [TITLE <cTitle>] ;
    [ACCELKEY <anAccel>] ;
    [GOTFOCUS <bGotFocus>] ;
    [LOSTFOCUS <bLostFocus>] ;
    [TABSTOP]  ;
    [NOTABSTOP];
    [TABGROUP <nTabGroup>] ;
    [VISIBLE] ;
    [INVISIBLE] ;
    [GROUP <cGroup>] ;
    [MULTICOLUMN] ;
    [NAME <cVarName>] ;
    [RESIZE <aResize> [SCALEFONT] ] ;
    [DRAG <bDrag> [DIALOG <bDD>] ;
    [DROP <bDrop> [CURSOR <nDropCursor>]

Arguments:

<nRow> and <nCol> are the row and column of the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE argument is used.
If no parent is assigned, then the parent is the Dialog box.
IF the PIXEL option is set to .TRUE. in DCGETOPTIONS, then
the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel
mode by including PIXEL as a command argument.

<uOutVar> is the output variable.  This may be initialized to
either a character string variable or an array.  If it is a
character string, then only one choice in the listbox will be
allowed and the choice will be returned as a character string
in the variable <uOutVar>.  If it is an array, then the listbox
will allow multiple choices which will be returned as a
set of characters in a single-dimensional array and stored
in <uOutVar>. It must not be a macro, however it may be a code
block that contains a macro. The <uOutVar> is automatically
anchored via a Get-Set codeblock created by DC_GetAnchorCB()
unless <uVar> is a custom Get-Set code block.

<aVar> is a single-dimensional array of character strings
which is used as the list box of items.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

SIZE <nWidth>,<nHeight> is the width and height of the
listbox.  If the PIXEL option is set to .TRUE. in DCGET
OPTIONS, then the numbers are in pixels otherwise they are
in standard text-based numbers.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.  If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

OBJECT <oObject> is the name of the variable to assign as a
storage place for this object.

FONT <cFont> is a character string defining an optional font.
The font string must conform to the Xbase++ standard, ie.
"10.Courier.Bold". It may also be a font object or a code block
that returns a character string or a font object to later
refresh with DC_GetRefresh().

MARKMODE <nMarkMode> is a constant from the following table:

 Constant                   Description

 XBPLISTBOX_MM_SINGLE   *)  Only one item can be marked
 XBPLISTBOX_MM_MULTIPLE     Multiple items can be marked
                            (special keys are ignored)
 XBPLISTBOX_MM_EXTENDED     Multiple items can be marked
                            (special keys are supported)

*) default

The above constants are defined in XBP.CH.
If XBPLISTBOX_MM_MULTIPLE is used, any number of items can be
marked and/or selected with the mouse.  The space bar toggles
the selection. The extended selection mode
(XBPLISTBOX_MM_EXTENDED) allows for selecting multiple items by
holding the left button down and moving the mouse. In addition,
the special keys Shift and Ctrl are supported.

SELECT <aSelect> is an array of pointers into <aVar>.  This
array is used to Pre-Select items in the list box.  For example,
to pre-select items 4, 10, and 15, <aSelect> will be equal to
{ 4, 10, 15 }.

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the listbox object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.

TOOLTIP <bcToolTip> is a character string which will display
as a "Tool Tip" next to the object when the cursor is passed
over the object. A semi-colon within the text indicates a new
line.  If <bcToolTip> is a code-block, it must return a character
string.  NOTE: The Tooltip painting method is run in another
thread, therefore the codeblock should not run code that points
to the current work area.  It may however, contain local, public
or private variables.

MESSAGE <bcMsg> is the message you want to display in the
message area of the dialogue screen defined by the DCMESSAGEBOX
command when the object is in focus.  Optionally, INTO <oMsgBox>
will designate which message box to display the message into.
If the INTO clause is not used, then the last message box in the
GetList is the default. <oMsgBox> may also be any object that
supports the :setCaption() method.If <bcMsg> is a code-block,
it must return a character string.

CURSOR <naCursor> may be either a numeric value or an array of
3 elements which defines an optional mouse pointer to use for
this object.  System mouse pointers start with
XBPWINDOW_POINTERTYPE_ and are defined in XPB.CH.  The default
pointer is XBPWINDOW_POINTERTYPE_POINTER.  <naCursor> may be a
numeric resource ID that points to a Bit-Map that has been
compiled with the resource compiler and linked to the .EXE.
<naCursor> may be a 3-element array described as follows:

  Element  Type  Description
  -------  ---- ---------------------------------------------
    [1]      C   Optional name of .DLL containing the pointer
                 resource.

    [2]      N   The numeric resource ID of the pointer.  If
                 element 1 is a NIL, then this resource must be
                 linked into the .EXE.

    [3]      N   The type of resource as defined in XBP.CH.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

COLOR <ncFGc>, <ncBGc> are foreground and background colors.
They may be character strings representing valid text-based
colors supported by SetColor() or they may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH. If <bncFGc> is a
code block is must return a 2-element array containing a
foreground and background color.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

EDITPROTECT <bProtect> is an optional condition tested during the
execution of the GUI gets by the DCREAD GUI command, before the
object receives input focus (before it is activated). When the
condition returns the value .T. (true), the object receives the
input focus.  Otherwise, it is skipped. <bProtect> is a code
block that must return a logical value when evaluated. The code
block is evaluated prior to the object receiving input focus.
This clause behaves similar to the WHEN clause with the exception
that the object is not disabled (grayed out).  The object is
passed as a parameter to the code block.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the object will be disabled and grayed.
If the value returned is .TRUE. then the object will be enabled.
The object is passed as a parameter to the code block.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.
The object is passed as a parameter to the code block.

ACCELKEY <anAccel> is a numeric "hot-key" assignment that will set
focus to the checkbox object when the hot-key is pressed.  The key
must be a valid key with the prefix xbeK_*.  These keys are
defined in APPEVENT.CH.  <anAccel> may also be an array of numeric
values to assign more than one key to the object.

DATALINK <bLink> is an optional code block that is evaluated
every time Get/Set codeblock is evaluated, ie when the data
is read from the <aVar> into the object except when using
a user-defined Get/Set code block.

GOTFOCUS <bGotFocus> is a code block that is evaluated when this
object receives input focus.  <bGotFocus> := {|uNIL1,uNIL2,self|...}

LOSTFOCUS <bLostFocus> is a code block that is evaluated when this
object loses input focus.  <bLostFocus> := {|uNIL1,uNIL2,self|...}

TABSTOP will cause the object (Xbase Part) to be set when using
the Tab key.  Note: When logical groups are defined in a dialog
using TABGROUP <nTabGroup>, TABSTOP is usually set to .T. (true)
for the first dialog element in the group.  This allows the first
dialog element of a group to be activated using the Tab key.

NOTABSTOP will cause the object (Xbase Part) to be ignored when
using the Tab key. This clause is needed only to override any
default setting of TabStop by the DCGETOPTIONS [TABSTOP] command.

TABGROUP <nTabGroup> allows objects (Xbase Parts) that are created
immediately after one another in the GetList to be combined into
logical groups. This allows the user to navigate within a dialog
from group to group by pressing the Tab key.  Within a group of
dialog elements navigation is performed using the cursor keys.

Only constants defined in the XBP.CH file can be used as values
for this instance variable.  The following table lists the
available constants:

#define constants for <nTabGroup>:

 Constant             Description

 XBP_NO_GROUP     *)  Dialog element does not belong to a group
 XBP_BEGIN_GROUP      Dialog element is the first in a group
                      (this begins the definition of the group)
 XBP_WITHIN_GROUP     Dialog element is within a group
 XBP_END_GROUP        Dialog element is the last in a group
                      (this ends the definition of the group)

*) Default value

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS

By default, the list box is displayed without a horizontal scroll
bar. If items in the list have more characters than can be
displayed in the width of the display window, a horizontal scroll
bar can be provided by using the HORIZSCROLL clause.

ITEMMARKED <bItemMarked> is a code block to evaluate when a data
row is highlighted in the picklist.  The code block must be
formatted as {| uNIL1, uNIL2, self | ... }.

ITEMSELECTED <bItemSelected> is a code block to evaluate when
a data row is selected with a double-click of the left mouse
button or by pressing the ENTER key in the browser.  The code
block must be formatted as {| uNIL1, uNIL2, self | ... }.

MULTICOLUMN causes items to be displayed in multiple columns
that can be scrolled horizontally. The vertical scrollbar is
automatically hidden and the HORIZSCROLL clause is ignored.

NAME <cVarName> is the variable name to assign to the GET
object (for HTML based applications.)

RESIZE <aResize> is an optional array of two (2) elements
used for resizing and repositioning the object when the parent
is resized.

NOTE: RESIZE is to be used in conjunction with the RESIZE clause
      of DCGETOPTIONS. See the RESIZE clause of DCGETOPTIONS for
      examples.

      The optional SCALEFONT clause will automatically scale the
      font size up or down when the object is resized.

DRAG <bDrag> is a codeblock to evaluate when the left mouse button
is clicked in the object and the drag is started.  The return
value of the code block will be stored in memory to be later
retrieved by the Drop operation. A pointer to the clicked on
object is passed to the code block.

DIALOG <bDD> is a codeblock that will evaluate when the drag is
started.  This is used to call a function that will create a
dialog window which will move with the mouse during the drag.
The dialog window will be destroyed upon the drop operation
or the release of the mouse.

Ex: DRAG {|o|o:getData()} DIALOG {|mp1,mp2,oXbp|DragDialog(mp1,mp2,oXbp)} ;

DROP <bDrop> is a codeblock to evaluate when the left mouse button
is released in the object and the drag is ended.  A pointer to
the object and the value stored in memory at the start of the
Drag are passed to the code block.

CURSOR <nDropCursor> is the mouse cursor that will show when it
is moved over this object during a drag operation.

Ex: DROP {|o,x|o:setData(x),o:invalidateRect()} ;
       CURSOR CURSOR POINTER_DATADROP_ASSIGN

SUBCLASS <cSubClass> is a string containing a class name that
will be used to create the class, rather than DC_XbpListBox().
This class should inherit from DC_XbpListBox().
See the example in \exp19\samples\subclass.

Notes:

GUI Applications : The listbox object created by @ DCLISTBOX is an object of the DC_XbpListBox() class which inherits from the XbpListBox() class, therefore it can be manipulated with any iVar or method supported by XbpListBox().

------------------

HTML Applications:

The listbox object created by @ DCLISTBOX is an object of the DC_HtmlListBox() class.

Examples:

  #include "dcdialog.ch"

  PROCEDURE Xtest()

  LOCAL GetList := {}, aFields, cField

  USE Customer

  aFields := Array(FCount())
  AFields( aFields ) // fill array with field list.

  @ 5,10 DCLISTBOX cField LIST aFields FONT "10.Courier"  ;
    SIZE 15,10

  DCREAD GUI ;
     TITLE 'List Box Demo' ;
     FIT ;
     ADDBUTTONS

Files:

DCDIALOG.CH

See Also:

   @ DCCOMBOBOX
   @ DCPICKLIST
   dc_vartolistbox()


@ DCMESSAGEBOX

Create a MESSAGE BOX area for displaying with GUI reader

The command DCMESSAGEBOX creates a message box at the top or the bottom of the dialog screen for displaying messages that are attached to objects. The Message Box object is added to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> Any Getlist object in the GetList array can have a message attached to it via the MESSAGE option for the respective command. When the object is brought into focus, the message is displayed in the message box.<br><br> DCMESSAGEBOX objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCRADIO, @..DCBUTTON, @..DCCHECKBOX or @..DCTABPAGE.<br><br>

Syntax:

[ @ <nRow>,<nCol> ] DCMESSAGEBOX ;
    [OBJECT <oMsgBox>] ;
    [TEXTOBJECT <oMsgBoxText>] ;
    [TYPE <nType>] ;
    [SIZE <nWidth> [,<nHeight>]] ;
    [PARENT <oParent>] ;
    [PARENTID <cParentId>] ;
    [FONT <bocFont>] ;
    [COLOR <bncFgC> [,<ncBgC>] ] ;
    [CARGO <xCargo>] ;
    [PRESENTATION <aPres>] ;
    [ALIGN <nAlign>] ;
    [PIXEL] ;
    [PREEVAL <bPreEval>] ;
    [EVAL <bEval>] ;
    [ID <cId>] ;
    [TITLE <cTitle>] ;
    [GROUP <cGroup>] ;
    [VISIBLE] ;
    [INVISIBLE] ;
    [MOTION] ;
    [RESIZE <aResize> [SCALEFONT] ]

Arguments:

OBJECT <oMsgBox> is the name of the variable to assign as a
storage place for the box portion of this object.

TYPE <nType> is the type of message box. Message boxes are created
using XbpStatic() objects, so valid constants start with the
prefix XBPSTATIC_TYPE_ and are listed in XBP.CH.  The default
is XBPSTATIC_TYPE_HALFTONEFRAME.

TEXTOBJECT <oMsgBoxText> is the name of the variable to assign
as a storage place for the text portion of the object :
XbpStatic() type text.

ALIGN <nAlign> is a numeric constant defined in DCDIALOG.CH.
There are two alignment options:

 MESSAGEBOX_TOP     Anchor to top of the dialog or parent.
 MESSAGEBOX_BOTTOM  Anchor to bottom of dialog or parent.

<nRow> and <nCol> is the starting location of the Message Box
in text-based coordinates, unless the PIXEL clause is used.  If
no <nRow> and <nCol> arguments are used, then the message box
is located in acordance with the ALIGN <nAlign> option.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.  If this
clause is not used, then the object will be displayed in the
top-level dialogue screen.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

SIZE <nWidth>, <nHeight> optionally define the size of the
message box.  If no size is given, then the message box will be
automatically sized horizontally to fit the parent window.  IF
the PIXEL option is set to .TRUE. in DCGETOPTIONS, then the
numbers are in pixels otherwise they are in standard text-based
coordinates.  You can also force the pixel mode by including
PIXEL in the command.

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the Message Box object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

FONT <cFont> is the font to use for the text that is displayed
in the message box.  The default font is "10.Helv". It may also
be a font object or a code block that returns a character string
or a font object to later refresh with DC_GetRefresh().

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

COLOR <ncFGc>, <ncBGc> are foreground and background colors.
They may be character strings representing valid text-based
colors supported by SetColor() or they may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH. If <bncFGc> is a
code block is must return a 2-element array containing a
foreground and background color.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS

MOTION determines whether messages are visible when the mouse is
placed over the object rather than when the object obtains focus.

RESIZE <aResize> is an optional array of two (2) elements
used for resizing and repositioning the object when the parent
is resized.

NOTE: RESIZE is to be used in conjunction with the RESIZE clause
      of DCGETOPTIONS. See the RESIZE clause of DCGETOPTIONS for
      examples.

      The optional SCALEFONT clause will automatically scale the
      font size up or down when the object is resized.

Notes:

The objects created by @ DCMESSAGEBOX are objects of the XbpStatic() class, therefore they can be manipulated with any iVar or method supported by XbpStatic(). Two objects are created, one for the static area and one for the message text.

Examples:

#include "dcdialog.ch"

PROCEDURE XTest()

LOCAL GetList := {}, cDesc, cMemo, oMsgBox, lOk

USE Collect NEW SHARED

cDesc := COLLECT->descrip
cMemo := COLLECT->memo

DCMESSAGEBOX oMsgBox

@ 2,0 DCSAY 'Enter Desc' GET cDesc ;
    MESSAGE 'Enter the full description of this item'

@ 5,0 DCMULTILINE cMemo FONT "10.Courier.New" SIZE 70,10 ;
    MESSAGE 'Tell us something about how you acquired this item'

DCREAD GUI ;
   TITLE 'Message Box Demo' ;
   TO lOk ;
   ADDBUTTONS ;
   FIT

IF lOk .AND. DC_RecLock()
  REPL COLLECT->memo WITH cMemo, ;
       COLLECT->descrip WITH cDesc
  UNLOCK
ENDIF

RETURN

Files:

DCDIALOG.CH


@ DCMULTILINE

Create a MULTILINE edit for displaying with GUI reader

The command @..DCMULTILINE creates a new multi-line edit definition and adds it to the array named GETLIST which is later processed by the DC_Read*() functions or by the DCREAD * commands. The GETLIST array must be first declared and initialized to the value of {}. <br><br> The command DCREAD GUI creates the DC_Xbp*() objects and activates the edit mode for all definitions found in the GetList array.<br><br> The command DCREAD HTML creates the DC_Html*() objects and writes the HTML source code.<br><br> A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> @..DCMULTILINE objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCRADIO, @..DCBUTTON, @..DCCHECKBOX or @..DCTABPAGE.<br><br> <br><br>

Syntax:

@ <nRow>,<nCol> DCMULTILINE <uVar> ;
    [PARENT <oParent>] ;
    [PARENTID <cParentId>] ;
    [VALID <bValid>] ;
    [WHEN <bWhen>] ;
    [HIDE <bHide>] ;
  * [EDITPROTECT <bProtect>] ;
    [SIZE <nWidth>,<nHeight>] ;
    [MESSAGE <bcMsg> [INTO <oMsgBox>]] ;
    [FONT <bocFont>] ;
    [COLOR <bncFgC> [,<ncBgC>] ] ;
    [HELPCODE <cHelpCode>] ;
  * [DATALINK <bLink>] ;
    [OBJECT <oObject>] ;
    [CARGO <xCargo>] ;
  * [READONLY] ;
  * [NOWORDWRAP] ;
  * [NOBORDER] ;
  * [NOVERTSCROLL] ;
  * [NOHORIZSCROLL] ;
  * [IGNORETAB] ;
  * [COMPATIBLE] ;
  * [PRESENTATION <aPres>] ;
  * [PIXEL] ;
  * [TOOLTIP <bcToolTip>] ;
  * [CURSOR <naCursor>] ;
    [PREEVAL <bPreEval>] ;
    [EVAL <bEval>] ;
    [RELATIVE <oRel>] ;
    [ID <cId>] ;
    [TITLE <cTitle>] ;
  * [ACCELKEY <nKey>] ;
  * [GOTFOCUS <bGotFocus>] ;
  * [LOSTFOCUS <bLostFocus>] ;
  * [TABSTOP] ;
  * [NOTABSTOP] ;
  * [TABGROUP <nTabGroup>] ;
  * [VISIBLE] ;
  * [INVISIBLE] ;
    [GROUP <cGroup>] ;
  * [EXITKEY <nExitKey>] ;
  * [MAXLINES <nMaxLines> [MESSAGE <bcMaxLinesMessage>]] ;
  * [LINELENGTH <nLineLength> [MESSAGE <bcLineLengthMessage>]] ;
  * [MAXCHARS <nMaxChars> [MESSAGE <bcMaxCharsMessage>]] ;
    [NAME <cVarName>] ;
  * [RESIZE <aResize> [SCALEFONT] ] ;
  * [GOBOTTOM] ;
    [DRAG <bDrag> [DIALOG <bDD>] ;
    [DROP <bDrop> [CURSOR <nDropCursor>] ;
    [SUBCLASS <cSubClass>]

Arguments:

GUI applications:

<nRow> and <nCol> are the row and column of the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE <oRel> argument is
used.  If no parent is assigned, then the parent is the Dialog
box.  IF the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel
mode by including PIXEL as a command argument.

HTML applications:

<nRow> and <nCol> are the row number and column number of
the table if the parent of this object is a DCTABLE. The
text will be inserted in the cell of the table defined by
the row/column.

<uVar> is the input/output variable.  This should be
initialized to a character string. It must not be a macro, however
it may be a code block that contains a macro. The <uVar> is
automatically anchored via a Get-Set codeblock created by
DC_GetAnchorCB() unless <uVar> is a custom Get-Set
code block.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

SIZE <nWidth>,<nHeight> is the width and height of the
multiline box.  If the PIXEL option is set to .TRUE. in DCGET
OPTIONS, then the numbers are in pixels otherwise they are
in standard text-based numbers.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.  If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

OBJECT <oObject> is the name of the variable to assign as a
storage place for this object.

FONT <cFont> is a character string defining an optional font.
The font string must conform to the Xbase++ standard, ie.
"10.Courier Bold". It may also be a font object or a code block
that returns a character string or a font object to later
refresh with DC_GetRefresh().

MESSAGE <bcMsg> is the message you want to display in the
message area of the dialogue screen defined by the DCMESSAGEBOX
command when the object is in focus.  Optionally, INTO <oMsgBox>
will designate which message box to display the message into.
If the INTO clause is not used, then the last message box in the
GetList is the default. <oMsgBox> may also be any object that
supports the :setCaption() method.If <bcMsg> is a code-block,
it must return a character string.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the object will be disabled and grayed.
If the value returned is .TRUE. then the object will be enabled.
The object is passed as a parameter to the code block.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.
The object is passed as a parameter to the code block.

EDITPROTECT <bProtect> is an optional condition tested during the
execution of the GUI gets by the DCREAD GUI command, before the
object receives input focus (before it is activated). When the
condition returns the value .T. (true), the object receives the
input focus.  Otherwise, it is skipped. <bProtect> is a code
block that must return a logical value when evaluated. The code
block is evaluated prior to the object receiving input focus.
This clause behaves similar to the WHEN clause with the exception
that the object is not disabled (grayed out).  The object is
passed as a parameter to the code block.

VALID <bValid> is an optional condition tested during the
execution of the GUI gets by the READ command before an
object loses input focus (before it is deactivated).  When
the condition returns the value .T. (true), the object
loses the input focus.  Otherwise, it remains active. <bValid>
is a code block that must return a logical value when it is
evaluated.  The object passed as a parameter to the code block.

HELPCODE <cHelp> is a character string that is passed to the
DC_HelpF1() function if F1 is pressed or the HELP button
is clicked when this object has focus.  This HELPCODE allows
the Help system to override the passing of the Procedure and
Varname for more specific context-help.

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the multiline object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.

READONLY will not allow editing of the text.  The entire text
area will be grayed.

NOWORDWRAP means that the text is not wrapped.  The default is
word-wrap ON so that it is completely displayed in the edit
window.  Individual text lines that contain more characters
than can be displayed within the edit window are automatically
wrapped at the spaces between words.  With NOWORDWRAP, new
lines are started in the edit window only when CRLF explicitly
appears in the edit buffer. Text lines that contain more
characters than can be displayed in the edit window are cut
off and the text must be horizontally scrolled in order to view
all the characters.  To enable WORDWRAP the NOHORIZSCROLL clause
must be used.

NOVERTSCROLL will suppress the vertical scrollbar on the right
side of the window.

NOHORIZSCROLL will suppress the horizontal scrollbar on the
bottom of the window.

IGNORETAB causes the Tab key to navigates between other objects
on the dialog screen and is not interpreted as a character.
The default action is for the Tab key character to be written
to the edit buffer.

NOBORDER suppress the painting of a border around the object.

COMPATIBLE will make navigation keys compatabile with those of
MemoEdit().  This means that keys like CTRL-R, CTRL-C, CRTL-E,
CRTL-X, CTRL-Y, etc. will be recognized in addition to all the
standard "windows-compatabile" keys.

TOOLTIP <bcToolTip> is a character string which will display
as a "Tool Tip" next to the object when the cursor is passed
over the object. A semi-colon within the text indicates a new
line.  If <bcToolTip> is a code-block, it must return a character
string.  NOTE: The Tooltip painting method is run in another
thread, therefore the codeblock should not run code that points
to the current work area.  It may however, contain local, public
or private variables.

CURSOR <naCursor> may be either a numeric value or an array of
3 elements which defines an optional mouse pointer to use for
this object.  System mouse pointers start with
XBPWINDOW_POINTERTYPE_ and are defined in XPB.CH.  The default
pointer is XBPWINDOW_POINTERTYPE_POINTER.  <naCursor> may be a
numeric resource ID that points to a Bit-Map that has been
compiled with the resource compiler and linked to the .EXE.
<naCursor> may be a 3-element array described as follows:

  Element  Type  Description
  -------  ---- ---------------------------------------------
    [1]      C   Optional name of .DLL containing the pointer
                 resource.

    [2]      N   The numeric resource ID of the pointer.  If
                 element 1 is a NIL, then this resource must be
                 linked into the .EXE.

    [3]      N   The type of resource as defined in XBP.CH.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

COLOR <ncFGc>, <ncBGc> are foreground and background colors.
They may be character strings representing valid text-based
colors supported by SetColor() or they may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH. If <bncFGc> is a
code block is must return a 2-element array containing a
foreground and background color.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

DATALINK <bLink> is an optional code block that is evaluated
every time Get/Set codeblock is evaluated, ie when the data
is read from the <uVar> into the object except when using
a user-defined Get/Set code block.  <bLink> is also
evaluated when DC_GetRefresh() is called unless the <lDataLink>
parameter of DC_GetRefresh() is .FALSE.

ACCELKEY <nKey> is a numeric "hot-key" assignment that will set
focus to the memo object when the hot-key is pressed.  The key
must be a valid key with the prefix xbeK_*.  These keys are
defined in APPEVENT.CH.

GOTFOCUS <bGotFocus> is a code block that is evaluated when this
object receives input focus.  <bGotFocus> := {|uNIL1,uNIL2,self|...}

LOSTFOCUS <bLostFocus> is a code block that is evaluated when this
object loses input focus.  <bLostFocus> := {|uNIL1,uNIL2,self|...}

TABSTOP will cause the object (Xbase Part) to be set when using
the Tab key.  Note: When logical groups are defined in a dialog
using TABGROUP <nTabGroup>, TABSTOP is usually set to .T. (true)
for the first dialog element in the group.  This allows the first
dialog element of a group to be activated using the Tab key.

NOTABSTOP will cause the object (Xbase Part) to be ignored when
using the Tab key. This clause is needed only to override any
default setting of TabStop by the DCGETOPTIONS [TABSTOP] command.

TABGROUP <nTabGroup> allows objects (Xbase Parts) that are created
immediately after one another in the GetList to be combined into
logical groups. This allows the user to navigate within a dialog
from group to group by pressing the Tab key.  Within a group of
dialog elements navigation is performed using the cursor keys.

Only constants defined in the XBP.CH file can be used as values
for this instance variable.  The following table lists the
available constants:

#define constants for <nTabGroup>:

 Constant             Description

 XBP_NO_GROUP     *)  Dialog element does not belong to a group
 XBP_BEGIN_GROUP      Dialog element is the first in a group
                      (this begins the definition of the group)
 XBP_WITHIN_GROUP     Dialog element is within a group
 XBP_END_GROUP        Dialog element is the last in a group
                      (this ends the definition of the group)

*) Default value

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().
VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS.

EXITKEY <nExitKey> defines a key to be used to move focus from
the MULTILINE object to the next GET or MULTILINE object in the
GetList.

MAXLINES <nMaxLines> is the maximum number of lines which may be
entered.  If the MESSAGE <bcMaxLinesMessage> clause is used, then
the message will also be displayed when the number of lines is
exceeded.  If the message is a string, then a message box will
display the contents of the string.  If the message is a code
block, it will be evaluated to display any custom message window.

LINELENGTH <nLineLength> is the maximum number of characters allowed
on a line. If the MESSAGE <bcLineLengthMessage> clause is used, then
the message will also be displayed when a line exceeds the
designated length. If the message is a string, then a message box
will display the contents of the string.  If the message is a code
block, it will be evaluated to display any custom message window.

MAXCHARS <nMaxChars> is the maximum number of characters which may
be entered.  If the MESSAGE <bcMaxCharsMessage> clause is used, then
the message will also be displayed when the number of characters
is exceeded.  If the message is a string, then a message box will
display the contents of the string.  If the message is a code
block, it will be evaluated to display any custom message window.

NAME <cVarName> is the variable name to assign to the GET
object (for HTML based applications.)

RESIZE <aResize> is an optional array of two (2) elements
used for resizing and repositioning the object when the parent
is resized.

NOTE: RESIZE is to be used in conjunction with the RESIZE clause
      of DCGETOPTIONS. See the RESIZE clause of DCGETOPTIONS for
      examples.

      The optional SCALEFONT clause will automatically scale the
      font size up or down when the object is resized.

GOBOTTOM will cause the cursor to scroll to the bottom of the
text in the mle object.

DRAG <bDrag> is a codeblock to evaluate when the left mouse button
is clicked in the object and the drag is started.  The return
value of the code block will be stored in memory to be later
retrieved by the Drop operation. A pointer to the clicked on
object is passed to the code block.

DIALOG <bDD> is a codeblock that will evaluate when the drag is
started.  This is used to call a function that will create a
dialog window which will move with the mouse during the drag.
The dialog window will be destroyed upon the drop operation
or the release of the mouse.

Ex: DRAG {|o|o:getData()} DIALOG {|mp1,mp2,oXbp|DragDialog(mp1,mp2,oXbp)} ;

DROP <bDrop> is a codeblock to evaluate when the left mouse button
is released in the object and the drag is ended.  A pointer to
the object and the value stored in memory at the start of the
Drag are passed to the code block.

CURSOR <nDropCursor> is the mouse cursor that will show when it
is moved over this object during a drag operation.

Ex: DROP {|o,x|o:setData(x),o:invalidateRect()} ;
       CURSOR CURSOR POINTER_DATADROP_ASSIGN

SUBCLASS <cSubClass> is a string containing a class name that
will be used to create the class, rather than DC_XbpMle().
This class should inherit from DC_XbpMle().
See the example in \exp19\samples\subclass.

Notes:

Clauses marked by an asterisk ( * ) are not supported by DCREAD HTML or DC_ReadHtml().

------------------

GUI applications:

The multiline object created by @ DCDIALOG is an object of the DC_XbpMLE() class which inherits from the XbpMle() class, therefore it can be manipulated with any iVar or method supported by XbpMLE().

------------------

HTML applications:

The multiline object created by @ DCDIALOG is an object of the DC_HtmlMLE() class.

Examples:

-- Example 1 (GUI) --

#include "dcdialog.ch"

PROCEDURE Xtest()

LOCAL GetList := {}, cMemo, lOk

USE COLLECT NEW SHARED

cMemo := COLLECT->memo

@ 0,0 DCMULTILINE cMemo FONT "10.Courier" SIZE 80,10

DCREAD GUI ;
   FIT ;
   ADDBUTTONS TO lOk

IF lOk .AND. DC_RecLock()
  REPL COLLECT->memo WITH cMemo
  UNLOCK
ENDIF

CLOSE collect

RETURN

-- Example 2 (HTML) --

#include "dcdialog.ch"
#include "dchtml.ch"

PROCEDURE Xtest_2()

LOCAL i, GetList[0], oForm, oHtml, oParent, cHtml, oMainHtml, ;
      aGetListItem, bBlock, oTable, cComment1, cComment2

DCFORM OBJECT oForm
DCTABLE OBJECT oTable PARENT oForm ROWS 2 COLUMNS 1 WIDTH '200'

cComment1 := 'This is memo 1'
cComment2 := 'This is memo 2'

@ 1,1 DCMULTILINE cComment1 PARENT oTable SIZE 30,10 NAME 'Memo1'
@ 2,1 DCMULTILINE cComment2 PARENT oTable SIZE 30,10 NAME 'Memo2'

DCREAD HTML TO cHtml

MemoWrit('TEST.HTM',cHtml)

RETURN

Files:

DCDIALOG.CH

See Also:

   @ DCKLMLE
   dc_htmlmle()


@ DCMXPUSHBUTTON

Create an MXPUSHBUTTON for displaying with GUI reader

The command @..DCMXPUSHBUTTON creates a new PushButton object and adds the object to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> @..DCMXPUSHBUTTON objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCRADIO, @..DCMULTILINE, @..DCCHECKBOX or @..DCTABPAGE.<br><br> @..DCMXPUSHBUTTON objects are derived from Joe Carrick's MxPushButton class. Each object may contain up to 3 captions of type text, bitmap or icon.

Syntax:

@ <nRow>, <nCol> DCMXPUSHBUTTON ;
                [TYPE <nType>]                                           ;
                [SIZE <nWidth> [,<nHeight>]]                                ;
                [CAPTION,CAPTION1 <ncoCaption1>                               ;
                  [CAPOS,CA1POS <nCapRow>, <nCapCol>]                  ;
                  [CASIZE,CA1SIZE <nCapWidth>, <nCapHeight>]           ;
                  [CATYPE,CA1TYPE <nCapType>]                          ;
                  [CAFONT,CA1FONT <cCapFont>]                          ;
                  [CAPARAMS,CA1PARAMS <aCapParams>]                    ;
                  [CARESTYPE,CA1RESTYPE <cCapResType>]                 ;
                  [CARESFILE,CA1RESFILE <cCapResFile>] ]               ;
                [BITMAP,CAPTION2 <ncoCaption2>                              ;
                  [BMPOS,CA2POS <nBmRow>, <nBmCol>]                    ;
                  [BMSIZE,CA2SIZE <nBmWidth>, <nBmHeight>]             ;
                  [BMFONT,CA2FONT <cBmFont>]                           ;
                  [BMTYPE,CA2TYPE <nBmType>]                           ;
                  [BMPARAMS,CA2PARAMS <aBmParams>]                     ;
                  [BMRESTYPE,CA2RESTYPE <cBmResType>]                  ;
                  [BMRESFILE,CA2RESFILE <cBmResFile>] ]                ;
                [ICON,CAPTION3 <ncoCaption3>                                  ;
                  [ICPOS,CA3POS <nIcRow>, <nIcCol>]                    ;
                  [ICSIZE,CA3SIZE <nIcWidth>, <nIcHeight>]             ;
                  [ICTYPE,CA3TYPE <nIcType>]                           ;
                  [ICFONT,CA3FONT <cIcFont>]                           ;
                  [ICPARAMS,CA3PARAMS <aIcParams>]                     ;
                  [ICRESTYPE,CA3RESTYPE <cIcResType>]                  ;
                  [ICRESFILE,CA3RESFILE <cIcResFile>] ]                ;
                [ACTION <bAction>]                                          ;
                [AUTOSIZE]               ;
                [POINTERFOCUS]           ;
                [PRESELECT]           ;
                [WHEN <bWhen>]                                              ;
                [MENU <oMenu>]                                              ;
                [PARENT <oParent>]                                          ;
                [PARENTID <cPID>]                                           ;
                [COLOR <ncFgC> [,<ncBgC>]]                                  ;
                [MESSAGE <cMsg> [INTO <oMsg>]]                              ;
                [HELPCODE <cHelpCode>]                                      ;
                [FONT <cFont>]                                              ;
                [PRESENTATION <aPres>]                                      ;
                [PIXEL]                              ;
                [OBJECT <oObject>]                                          ;
                [TOOLTIP <cToolTip>]                                        ;
                [CURSOR <nCursor>]                                          ;
                [CARGO <xCargo>]                                            ;
                [EVAL <bEval>]                                              ;
                [PREEVAL <bPreEval>]                                        ;
                [POSTEVAL <bPostEval>]                                      ;
                [HIDE <bHide>]                                              ;
                [EDITPROTECT <bProtect>]                                    ;
                [TITLE <cTitle> ]                                           ;
                [RELATIVE <oRel> ]                                          ;
                [ID <cId>]                                                  ;
                [ACCELKEY <nAccel>]                                         ;
                [GOTFOCUS <bGotFocus>]                                      ;
                [LOSTFOCUS <bLostFocus>]                                    ;
                [TABSTOP]]                      ;
                [NOTABSTOP]               ;
                [TABGROUP <nTabGroup>]                                      ;
                [VISIBLE]                      ;
                [INVISIBLE]                ;
                [GROUP <cGroup>]                                            ;
                [SOUND <abSound>]                                           ;
                [CLASS <bcClass>]                                           ;
                [RESIZE <aReSize>]                                          ;

Arguments:

<nRow> and <nCol> are the row and column of the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE argument is used.
If no parent is assigned, then the parent is the Dialog box.
IF the PIXEL option is set to .TRUE. in DCGETOPTIONS, then
the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel
mode by including PIXEL as a command argument.

TYPE <nType> is the type of the MxPushButton.

MX_NONE, MX_3D, MX_RAISED, MX_FLAT, MX_FLYOVER defined in MX.CH.
Default is MX_NONE. (Standard PushButton)
Note: MX_3D and MX_RAISED are the same as MX_NONE
      MX_FLAT does not respond to mouse movement
      MX_FLYOVER is only raised when the mouse is positoned over the Pushbutton

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

SIZE <nWidth>,<nHeight> is the width and height of the
PushButton.  If the PIXEL option is set to .TRUE. in DCGET
OPTIONS, then the numbers are in pixels otherwise they are
in standard text-based numbers.

CAPTION, CAPTION1 <cnoCaption1> is caption #1 of the
PushButton object. The caption may be one of the following:

 1) A character string.  An ampersand (&) preceding a character in
    the text assigns the ALT-<char> key as a hotkey for the
    pushbutton and underlines the character.  A tilde (~) preceding
    the character will only underline the character and will not
    enable the hot-key.  A tilde (~) could be used with the
    ACCELKEY clause to establish the hot key(s).

 2) A bitmap resource. The numeric resource ID of the bitmap is
    assigned to the instance variable.  If a resource ID is used,
    it must be defined in a resource file that is linked to the
    EXE file using the resource compiler.

 3) A bitmap object created with the XbpBitMap() class.

CAPOS,CA1POS <nCapRow>,<nCapCol> are the row and column coordinates
within the pushbutton of caption #1.  If the PIXEL option is
set to .TRUE. then the numbers are in pixels otherwise they are
in standard text-based numbers.

CASIZE,CA1SIZE <nCapWidth>, <nCapHeight> are the width and height
of caption #1.  If the PIXEL option is set to .TRUE. then
the numbers are in pixels otherwise they are in standard text-based
numbers.

CATYPE,CA1TYPE <nCapType> is the type of caption for caption #1.
Standard types are XBPSTATIC_TYPE_TEXT, XBPSTATIC_TYPE_ICON,
or XBPSTATIC_TYPE_BITMAP.  If this clause is not used then the
type is text and the caption must also be text.

CAFONT,CA1FONT <cCapFont> is the font for caption #1 if
the caption is type text.  If this parameter is not used, then
the font defaults to 8.Arial.
                          ;
CAPARAMS,CA1PARAMS <aCapParams> is an array of presentation
parameters for caption #1.  This must match an object of
the type XbpStatic.
                    ;
CARESTYPE,CA1RESTYPE <cCapResType> provides support for bitmap
resources of type BMP, PNG, GIF and JPEG that have been linked
into a .RES file to be used for caption #1.

Example: CARESTYPE GIF

// myres.arc
USERDEF GIF
2000 = FILE ".\GIFChart.GIF"

CARESFILE,CA1RESFILE <cCapResFile> is the name of the .DLL that
contains the resource stated in the CARESTYPE <cCapResType> clause.
If this parameter is not used, then the resource must be in the
.EXE.

BITMAP, CAPTION2 <cnoCaption2> is caption #2 of the
PushButton object. The caption may be one of the following:

 1) A character string.  An ampersand (&) preceding a character in
    the text assigns the ALT-<char> key as a hotkey for the
    pushbutton and underlines the character.  A tilde (~) preceding
    the character will only underline the character and will not
    enable the hot-key.  A tilde (~) could be used with the
    ACCELKEY clause to establish the hot key(s).

 2) A bitmap resource. The numeric resource ID of the bitmap is
    assigned to the instance variable.  If a resource ID is used,
    it must be defined in a resource file that is linked to the
    EXE file using the resource compiler.

 3) A bitmap object created with the XbpBitMap() class.

BMPOS,CA2POS <nBmRow>,<nBmCol> are the row and column coordinates
within the pushbutton of caption #2.  If the PIXEL option is
set to .TRUE. then the numbers are in pixels otherwise they are
in standard text-based numbers.

BMSIZE,CA2SIZE <nBmWidth>, <nBmHeight> are the width and height
of the caption #2.  If the PIXEL option is set to .TRUE. then
the numbers are in pixels otherwise they are in standard text-based
numbers.

BMTYPE,CA2TYPE <nBmType> is the type of caption for caption #2.
Standard types are XBPSTATIC_TYPE_TEXT, XBPSTATIC_TYPE_ICON,
or XBPSTATIC_TYPE_BITMAP.  If this clause is not used then the
type is bitmap and the caption must also be a bitmap.

BMFONT,CA2FONT <cBmFont> is the font for the caption #2 if
the caption is type text.  If this parameter is not used, then
the font defaults to 8.Arial.
                          ;
BMPARAMS,CA2PARAMS <aBmParams> is an array of presentation
parameters for caption #2.  This must match an object of
the type XbpStatic.
                    ;
BMRESTYPE,CA2RESTYPE <cBmResType> provides support for bitmap
resources of type BMP, PNG, GIF and JPEG that have been linked
into a .RES file to be used for caption #2.

Example: BMRESTYPE GIF

// myres.arc
USERDEF GIF
2000 = FILE ".\GIFChart.GIF"

BMRESFILE,CA2RESFILE <cBmResFile> is the name of the .DLL that
contains the resource stated in the BMRESTYPE <cBmResType> clause.
If this parameter is not used, then the resource must be in the
.EXE.

ICON, CAPTION3 <cnoCaption3> is caption #3 of the
PushButton object. The caption may be one of the following:

 1) A character string.  An ampersand (&) preceding a character in
    the text assigns the ALT-<char> key as a hotkey for the
    pushbutton and underlines the character.  A tilde (~) preceding
    the character will only underline the character and will not
    enable the hot-key.  A tilde (~) could be used with the
    ACCELKEY clause to establish the hot key(s).

 2) A bitmap resource. The numeric resource ID of the bitmap is
    assigned to the instance variable.  If a resource ID is used,
    it must be defined in a resource file that is linked to the
    EXE file using the resource compiler.

 3) A bitmap object created with the XbpBitMap() class.

ICPOS,CA3POS <nIcRow>,<nIcCol> are the row and column coordinates
within the pushbutton of caption #3.  If the PIXEL option is
set to .TRUE. then the numbers are in pixels otherwise they are
in standard text-based numbers.

ICSIZE,CA3SIZE <nIcWidth>, <nIcHeight> are the width and height
of the caption #3.  If the PIXEL option is set to .TRUE. then
the numbers are in pixels otherwise they are in standard text-based
numbers.

ICTYPE,CA3TYPE <nIcType> is the type of caption for caption #3.
Standard types are XBPSTATIC_TYPE_TEXT, XBPSTATIC_TYPE_ICON,
or XBPSTATIC_TYPE_BITMAP.  If this clause is not used then the
type is icon and the caption must also be an icon.

ICFONT,CA3FONT <cIcFont> is the font for the caption #3 if
the caption is type text.  If this parameter is not used, then
the font defaults to 8.Arial.
                          ;
ICPARAMS,CA3PARAMS <aIcParams> is an array of presentation
parameters for caption #3.  This must match an object of
the type XbpStatic.
                    ;
ICRESTYPE,CA3RESTYPE <cIcResType> provides support for bitmap
resources of type BMP, PNG, GIF and JPEG that have been linked
into a .RES file to be used for caption #3.

Example: ICRESTYPE GIF

// myres.arc
USERDEF GIF
2000 = FILE ".\GIFChart.GIF"

ICRESFILE,CA3RESFILE <cIcResFile> is the name of the .DLL that
contains the resource stated in the ICRESTYPE <cIcResType> clause.
If this parameter is not used, then the resource must be in the
.EXE.

ACTION <bAction> is a codeblock that is to be evaluated
when the pushbutton is activated.

AUTOSIZE automatically fits the size of the pushbutton to the
caption.

POINTERFOCUS Indicates whether the pushbutton receives input focus
when the mouse is clicked on it.

PRESELECT determines whether the pushbutton initally has the input
focus.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.  If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

OBJECT <oObject> is the name of the memory variable to assign to
this object.

FONT <cFont> is a character string defining an optional font.
The font string must conform to the Xbase++ standard, ie.
"10.Courier Bold". It may also be a font object or a code block
that returns a character string or a font object to later
refresh with DC_GetRefresh().

MESSAGE <bcMsg> is the message you want to display in the
message area of the dialogue screen defined by the DCMESSAGEBOX
command when the object is in focus.  Optionally, INTO <oMsgBox>
will designate which message box to display the message into.
If the INTO clause is not used, then the last message box in the
GetList is the default. <oMsgBox> may also be any object that
supports the :setCaption() method.If <bcMsg> is a code-block,
it must return a character string.

HELPCODE <cHelp> is a character string that is passed to the
DC_HelpF1() function if F1 is pressed or the HELP button
is clicked when this object has focus.  This HELPCODE allows
the Help system to override the passing of the Procedure and
Varname for more specific context-help.

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the pushbutton object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.

TOOLTIP <bcToolTip> is a character string which will display
as a "Tool Tip" next to the object when the cursor is passed
over the object. A semi-colon within the text indicates a new
line.  If <bcToolTip> is a code-block, it must return a character
string.  NOTE: The Tooltip painting method is run in another
thread, therefore the codeblock should not run code that points
to the current work area.  It may however, contain local, public
or private variables.

CURSOR <naCursor> may be either a numeric value or an array of
3 elements which defines an optional mouse pointer to use for
this object.  System mouse pointers start with
XBPWINDOW_POINTERTYPE_ and are defined in XPB.CH.  The default
pointer is XBPWINDOW_POINTERTYPE_POINTER.  <naCursor> may be a
numeric resource ID that points to a Bit-Map that has been
compiled with the resource compiler and linked to the .EXE.
<naCursor> may be a 3-element array described as follows:

  Element  Type  Description
  -------  ---- ---------------------------------------------
    [1]      C   Optional name of .DLL containing the pointer
                 resource.

    [2]      N   The numeric resource ID of the pointer.  If
                 element 1 is a NIL, then this resource must be
                 linked into the .EXE.

    [3]      N   The type of resource as defined in XBP.CH.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

Use the clause CARGO 'CANCEL' if the pushbutton is to be used
to exit a dialog without testing validations.  This will insure
that if the pushbutton is clicked while in a DCGET with a
validation the validation code block will not be evaluated.

COLOR <ncFGc>, <ncBGc> are foreground and background colors.
They may be character strings representing valid text-based
colors supported by SetColor() or they may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH. If <bncFGc> is a
code block is must return a 2-element array containing a
foreground and background color.  The COLOR clause is supported
only when using the STATIC clause.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the object will be disabled and grayed.
If the value returned is .TRUE. then the object will be enabled.
The object is passed as a parameter to the code block.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.
The object is passed as a parameter to the code block.

ACCELKEY <anAccel> is a numeric "hot-key" assignment that will set
focus to the pushbutton object and activate its associated code block
when the hot-key is pressed.  The key must be a valid key with
the prefix xbeK_*.  These keys are defined in APPEVENT.CH.
<anAccel> may also be an array of numeric values to assign more
than one key to the object.

GOTFOCUS <bGotFocus> is a code block that is evaluated when this
object receives input focus.  <bGotFocus> := {|uNIL1,uNIL2,self|...}

LOSTFOCUS <bLostFocus> is a code block that is evaluated when this
object loses input focus.  <bLostFocus> := {|uNIL1,uNIL2,self|...}

TABSTOP will cause the object (Xbase Part) to be set when using
the Tab key.  Note: When logical groups are defined in a dialog
using TABGROUP <nTabGroup>, TABSTOP is usually set to .T. (true)
for the first dialog element in the group.  This allows the first
dialog element of a group to be activated using the Tab key.

NOTABSTOP will cause the object (Xbase Part) to be ignored when
using the Tab key. This clause is needed only to override any
default setting of TabStop by the DCGETOPTIONS [TABSTOP] command.

TABGROUP <nTabGroup> allows objects (Xbase Parts) that are created
immediately after one another in the GetList to be combined into
logical groups. This allows the user to navigate within a dialog
from group to group by pressing the Tab key.  Within a group of
dialog elements navigation is performed using the cursor keys.

Only constants defined in the XBP.CH file can be used as values
for this instance variable.  The following table lists the
available constants:

#define constants for <nTabGroup>:

 Constant             Description

 XBP_NO_GROUP     *)  Dialog element does not belong to a group
 XBP_BEGIN_GROUP      Dialog element is the first in a group
                      (this begins the definition of the group)
 XBP_WITHIN_GROUP     Dialog element is within a group
 XBP_END_GROUP        Dialog element is the last in a group
                      (this ends the definition of the group)

*) Default value

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS.

The following options are supported by eXPress++ 1.7 or later:

When the STATIC * clause is used, a class created from the
XbpDialog() class is used instead of the XbpPushButton() class.
This allows for the creation of complex pushbuttons by allowing
the pushbutton object to be a parent for any other object such
as DCSTATIC or DCSAY for the display of text, icons, bitmaps
etc. on the button.

RESIZE <aResize> is an optional array of two (2) elements
used for resizing and repositioning the object when the parent
is resized.

NOTE: RESIZE is to be used in conjunction with the RESIZE clause
      of DCGETOPTIONS. See the RESIZE clause of DCGETOPTIONS for
      examples.

Notes:

The object created by @ DCMXPUSHBUTTON is an object of the MxPushButton() class, therefore it can be manipulated with any iVar or method supported by MxPushButton() class.

Use the clause CARGO 'CANCEL' if the pushbutton is to be used to exit a dialog without testing validations. This will insure that if the pushbutton is clicked while in a DCGET with a validation the validation code block will not be evaluated. The function DC_BitmapTransparentColor() may be used to set the default transparent color for pushbuttons that have bitmaps as captions.

Examples:

Run XDEMO.EXE - Sample Group 6 - MxPushButton

Files:

DCMXBUTT.CH

See Also:

   @ DCTOOLBAR
   @ DCPUSHBUTTON
   DCMXADDBUTTON


@ DCOBJECT

Define an existing object for displaying with GUI reader

The command DCOBJECT is used to create a reference to an already created object and adds it to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> DCOBJECT is used add a reference to an "existing" object. This command is used when there is a requirement to include an object in a dialog that has been already created by another routine.

Syntax:

@ <nRow>,<nCol> DCOBJECT <oObject> ;
    [PARENT <oParent>] ;
    [PARENTID <cParentId>] ;
    [MESSAGE <bcMsg> [INTO <oMsgBox>]] ;
    [HIDE <bHide>] ;
    [WHEN <bWhen>] ;
    [EDITPROTECT <bProtect>] ;
    [VALID <bValid>] ;
    [HELPCODE <cHelpCode>] ;
    [TOOLTIP <bcToolTip>] ;
    [CURSOR <naCursor>] ;
    [CARGO <xCargo>] ;
    [PREEVAL <bPreEval>] ;
    [EVAL <bEval] ;
    [PIXEL] ;
    [RELATIVE <oRel>] ;
    [ID <cId>] ;
    [TITLE <cTitle>] ;
    [ACCELKEY <anAccel>] ;
    [GOTFOCUS <bGotFocus>] ;
    [LOSTFOCUS <bLostFocus>] ;
    [TABSTOP] ;
    [NOTABSTOP] ;
    [TABGROUP <nTabGroup>] ;
    [GROUP <cGroup>] ;
    [RESIZE <aResize>]

Arguments:

<nRow>, <nCol> are the coordinates on the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE <oRel> argument is
used.  If no parent is assigned, then the parent is the Dialog
box.  IF the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel mode by
including PIXEL as a command argument.
<nRow> is stored in element nGETLIST_STARTROW.
<nCol> is stored in element nGETLIST_STARTCOL.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.  If this
clause is not used, then the object will be displayed in the
top-level dialogue screen or in the object set with the
DCSETPARENT command. This is converted to a code-block by
the function DC_GetAnchorCB() and is stored in element
oGETLIST_PARENT.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

MESSAGE <cMsg> is the message you want to display in the
message area of the dialogue screen defined by the DCMESSAGEBOX
command when the object is in focus.  Optionally, INTO <oMsgBox>
will designate which message box to display the message into.
If the INTO clause is not used, then the last message box in the
GetList is the default. <oMsgBox> may also be any object that
supports the :setCaption() method.  If <bcMsg> is a code-block,
it must return a character string.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the object will be disabled and grayed.
If the value returned is .TRUE. then the object will be enabled.
The code block is stored in element bGETLIST_WHEN.
The object is passed as a parameter to the code block.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.
The object is passed as a parameter to the code block.

EDITPROTECT <bProtect> is an optional condition tested during the
execution of the GUI gets by the DCREAD GUI command, before the
object receives input focus (before it is activated). When the
condition returns the value .T. (true), the object receives the
input focus.  Otherwise, it is skipped. <bProtect> is a code
block that must return a logical value when evaluated. The code
block is evaluated prior to the object receiving input focus.
This clause behaves similar to the WHEN clause with the exception
that the object is not disabled (grayed out).  The object is
passed as a parameter to the code block.

VALID <bValid> is an optional condition tested during the
navigation through the dialog objects when an object loses
focus (before it is deactivated).  If the condition returns the
value .T. (true), the object loses the input focus, otherwise,
it remains active. <bValid> is a code block that must return a
logical value when it is evaluated.  The object is passed to the
code block prior to the object losing input focus.  The
code block is stored in element bGETLIST_VALID.

HELPCODE <cHelp> is a character string that is passed to the
DC_HelpF1() function if F1 is pressed or the HELP button
is clicked when this object has focus.  This HELPCODE allows
the Help system to override the passing of the Procedure and
Varname for more specific context-help.  The help code is
stored in element cGETLIST_HELPCODE.

TOOLTIP <bcToolTip> is a character string which will display
as a "Tool Tip" next to the object when the cursor is passed
over the object. A semi-colon within the text indicates a new
line.  If <bcToolTip> is a code-block, it must return a character
string.  NOTE: The Tooltip painting method is run in another
thread, therefore the codeblock should not run code that points
to the current work area.  It may however, contain local, public
or private variables.

CURSOR <naCursor> may be either a numeric value or an array of
3 elements which defines an optional mouse pointer to use for
this object.  System mouse pointers start with
XBPWINDOW_POINTERTYPE_ and are defined in XPB.CH.  The default
pointer is XBPWINDOW_POINTERTYPE_POINTER.  <naCursor> may be a
numeric resource ID that points to a Bit-Map that has been
compiled with the resource compiler and linked to the .EXE.
<naCursor> may be a 3-element array described as follows:

  Element  Type  Description
  -------  ---- ---------------------------------------------
    [1]      C   Optional name of .DLL containing the pointer
                 resource.

    [2]      N   The numeric resource ID of the pointer.  If
                 element 1 is a NIL, then this resource must be
                 linked into the .EXE.

    [3]      N   The type of resource as defined in XBP.CH.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

<xCargo> is stored in element xGETLIST_CARGO.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to evaluate after the object is
created.  The object is passed as a parameter to the code block.

ACCELKEY <anAccel> is a numeric "hot-key" assignment that will set
focus to the checkbox object when the hot-key is pressed.  The key
must be a valid key with the prefix xbeK_*.  These keys are
defined in APPEVENT.CH.  <anAccel> may also be an array of numeric
values to assign more than one key to the object.

GOTFOCUS <bGotFocus> is a code block that is evaluated when this
object receives input focus.  <bGotFocus> := {|uNIL1,uNIL2,self|...}

LOSTFOCUS <bLostFocus> is a code block that is evaluated when this
object loses input focus.  <bLostFocus> := {|uNIL1,uNIL2,self|...}

TABSTOP will cause the object (Xbase Part) to be set when using
the Tab key.  Note: When logical groups are defined in a dialog
using TABGROUP <nTabGroup>, TABSTOP is usually set to .T. (true)
for the first dialog element in the group.  This allows the first
dialog element of a group to be activated using the Tab key.

NOTABSTOP will cause the object (Xbase Part) to be ignored when
using the Tab key. This clause is needed only to override any
default setting of TabStop by the DCGETOPTIONS [TABSTOP] command.

TABGROUP <nTabGroup> allows objects (Xbase Parts) that are created
immediately after one another in the GetList to be combined into
logical groups. This allows the user to navigate within a dialog
from group to group by pressing the Tab key.  Within a group of
dialog elements navigation is performed using the cursor keys.

Only constants defined in the XBP.CH file can be used as values
for this instance variable.  The following table lists the
available constants:

#define constants for <nTabGroup>:

 Constant             Description

 XBP_NO_GROUP     *)  Dialog element does not belong to a group
 XBP_BEGIN_GROUP      Dialog element is the first in a group
                      (this begins the definition of the group)
 XBP_WITHIN_GROUP     Dialog element is within a group
 XBP_END_GROUP        Dialog element is the last in a group
                      (this ends the definition of the group)

*) Default value

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

RESIZE <aResize> is an optional array of two (2) elements
used for resizing and repositioning the object when the parent
is resized.

NOTE: RESIZE is to be used in conjunction with the RESIZE clause
      of DCGETOPTIONS. See the RESIZE clause of DCGETOPTIONS for
      examples.

Examples:

#include "dcdialog.ch"

FUNCTION CreateIndexDialog()

LOCAL cIndexFile, lIsCDX, lDescend, lUnique, cIndexKey, cIndexFor,;
      cTagName, lNewIndex, GetList := {}, GetOptions, oStruDlg, lOk, ;
      oStatic

oStruDlg := DC_DBSTRUW(1,5,9,75,.f.) // create browse window
                                     // that lists fields
cIndexFile := SPACE(80)
cIndexKey := SPACE(200)
cIndexFor := SPACE(200)
cTagName := SPACE(10)
STOR .f. TO lIsCDX, lDescend, lUnique

@ 0,7 DCSTATIC TYPE XBPSTATIC_TYPE_TEXT OBJECT oStatic SIZE 76,10.5

@ 0,0 DCOBJECT oStruDlg PARENT oStatic EVAL {|o|o:show()}

@ 11,7 DCSAY 'File Name' GET cIndexFile GETSIZE 50 ;
       VALID {||DC_ReadEmpty(cIndexFile)}

@ 12,7 DCSAY 'Index Key' GET cIndexKey GETSIZE 50 ;
       VALID {||DC_ReadEmpty(cIndexKey)}

@ 13,7 DCSAY 'Index FOR condition' GET cIndexFor GETSIZE 50 ;
       POPUP {|c|DC_Query(c)}

@ 14,7 DCSAY 'Tag Name' GET cTagName PICT '@!'

@ 16,7 DCCHECKBOX lUnique PROMPT 'Unique Index'
@ 17,7 DCCHECKBOX lDescend PROMPT 'Descending Index'
@ 18,7 DCCHECKBOX lIsCDX PROMPT 'Combined Index'

DCGETOPTIONS SAYRIGHT SAYWIDTH 120
DCREAD GUI FIT ADDBUTTONS TO lOk MODAL ;
   OPTIONS GetOptions

RETURN  { cIndexFile, cIndexKey, cIndexFor, cTagName, ;
          lUnique, lDescend, lIsCDX }

Files:

DCDIALOG.CH

See Also:

   USER-DEFINED COMMANDS


@ DCPICKLIST

Create a PICKLIST dialog object for displaying with GUI reader

The command @..DCPICKLIST creates a new PickList object and adds the object to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> DCPICKLIST is a dialog that consists of two parts, an "Available Items" component and a "Selected Items" component. The "Available Items" area contains a list of items which are transferred to the "Selected Items" area when the user selects an item an transfers the item with a click on the '>' or '>>' button. "Selected Items" can also be transferred back to the "Avaialable Items" area by clicking on the '<' button or the '<<' button.<br><br> @..DCPICKLIST objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCRADIO, @..DCPUSHBUTTON, @..DCCHECKBOX or @..DCTABPAGE.<br><br>

Syntax:

@ <nRow>, <nCol> DCPICKLIST <aPick> LIST <aList> ;
    [DATALINK <bLink>]  ;
    [PARENT <oParent>] ;
    [OBJECT <oObject>] ;
    [COLOR <fgC> [, <bgC> ]] ;
    [FONT <bocFont>] ;
    [SIZE <nWidth> [, <nHeight>]] ;
    [CAPTION <cLeftCap> [,<cRightCap>]] ;
    [WHEN <bWhen>] ;
    [HIDE <bHide>] ;
    [PREEVAL <bPreEval>] ;
    [EVAL <bEval>] ;
    [RELATIVE <oRel>] ;
    [TOOLTIP <cToolTip>] ;
    [ID <cId>] ;
    [TITLE <cTitle>] ;
    [ACCELKEY <anAccel>] ;
    [GOTFOCUS <bGotFocus>] ;
    [LOSTFOCUS <bLostFocus>] ;
    [VISIBLE] ;
    [INVISIBLE] ;
    [GROUP <cGroup>] ;
    [IMMEDIATE] ;
    [SUBCLASS <cSubClass>]

Arguments:

<nRow>, <nCol> are the coordinates on the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE <oRel> argument is
used.  If no parent is assigned, then the parent is the Dialog
box.  IF the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel mode by
including PIXEL as a command argument.

<aPick> is a memory variable containing the array which will be
created from the picked items.

LIST <aList> is a memory variable containing a single-dimensional
array of character strings.  This is the "Available Items"
array.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

OBJECT <oObject> is the name of the variable to assign as a
storage place for this object.

DATALINK <bLink> is a code block that is evaluated when the
user clicks on OK after selecting the list.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object. If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

COLOR <ncFGc>, <ncBGc> are foreground and background colors.
They may be character strings representing valid text-based
colors supported by SetColor() or they may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH. If <bncFGc> is a
code block is must return a 2-element array containing a
foreground and background color.

FONT <font> is the name of the font to use for both the
directory and file dialog boxes. It may character string, a font
object or a code block that returns a character string or a font
object to later refresh with DC_GetRefresh().

SIZE <nWidth>,<nHeight> is the width and height of the
listbox.  If the PIXEL option is set to .TRUE. in DCGET
OPTIONS, then the numbers are in pixels otherwise they are
in standard text-based numbers.  The "Available Items" dialog
component occupies 40% of the total width, the "Selected Items"
dialog component occupies 40% of the total width and the select
buttons occupy 20% of the total width.

CAPTION <cLeftCap>, <cRightCap> are the captions in the left
and right pick areas of the dialog respectively, ex "Available
Fields" and "Selected Fields".

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the dialog object is created.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TOOLTIP <cToolTip> is a character string which will display
as a "Tool Tip" next to the object when the cursor is passed
over the object.  If <bcToolTip> is a code-block, it must return
a character string.  NOTE: The Tooltip painting method is run in
another thread, therefore the codeblock should not run code that
points to the current work area.  It may however, contain
local, public or private variables.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the object will be disabled and grayed.
If the value returned is .TRUE. then the object will be enabled.
The object is passed as a parameter to the code block.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.
The object is passed as a parameter to the code block.

ACCELKEY <anAccel> is a numeric "hot-key" assignment that will set
focus to the checkbox object when the hot-key is pressed.  The key
must be a valid key with the prefix xbeK_*.  These keys are
defined in APPEVENT.CH.  <anAccel> may also be an array of numeric
values to assign more than one key to the object.

GOTFOCUS <bGotFocus> is a code block that is evaluated when this
object receives input focus.  <bGotFocus> := {|uNIL1,uNIL2,self|...}

LOSTFOCUS <bLostFocus> is a code block that is evaluated when this
object loses input focus.  <bLostFocus> := {|uNIL1,uNIL2,self|...}

TABSTOP will cause the object (Xbase Part) to be set when using
the Tab key.  Note: When logical groups are defined in a dialog
using TABGROUP <nTabGroup>, TABSTOP is usually set to .T. (true)
for the first dialog element in the group.  This allows the first
dialog element of a group to be activated using the Tab key.

NOTABSTOP will cause the object (Xbase Part) to be ignored when
using the Tab key. This clause is needed only to override any
default setting of TabStop by the DCGETOPTIONS [TABSTOP] command.

TABGROUP <nTabGroup> allows objects (Xbase Parts) that are created
immediately after one another in the GetList to be combined into
logical groups. This allows the user to navigate within a dialog
from group to group by pressing the Tab key.  Within a group of
dialog elements navigation is performed using the cursor keys.

Only constants defined in the XBP.CH file can be used as values
for this instance variable.  The following table lists the
available constants:

#define constants for <nTabGroup>:

 Constant             Description

 XBP_NO_GROUP     *)  Dialog element does not belong to a group
 XBP_BEGIN_GROUP      Dialog element is the first in a group
                      (this begins the definition of the group)
 XBP_WITHIN_GROUP     Dialog element is within a group
 XBP_END_GROUP        Dialog element is the last in a group
                      (this ends the definition of the group)

*) Default value

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS.

IMMEDIATE forces the update of the array <aPick> every time an
item is added rather than requiring a click of the OK button.

SUBCLASS <cSubClass> is a string containing a class name that
will be used to create the class, rather than DC_XbpPickList().
This class should inherit from DC_XbpPickList().
See the example in \exp19\samples\subclass.

Examples:

/*
This example will display a list of fields in the
"Available Fields" selection, allow the operator to
select a set of fields, then display a Browse of the
database for the fields selected.
*/

#include "dcpick.ch"

PROCEDURE XTest( )

LOCAL GetList := {}, GetOptions, cAlias, aListField, ;
      aPickField, oBrowse, oDialog

USE COLLECT NEW SHARED

cAlias := 'COLLECT'
aListField := Array(FCount())
AFields(aListField)

@ 2,3 DCPICKLIST aPickField LIST aListField ;
   CAPTION "Available Fields", "Selected Fields" ;
   SIZE 35,12 ;
   DATALINK {||BrowseCollect(cAlias,oDialog,@oBrowse,@aPickField)}

DCGETOPTIONS ;
   WINDOW HEIGHT 360 ;
   WINDOW WIDTH 600

DCREAD GUI ;
   TITLE "Picklist Demo" ;
   OPTIONS GetOptions ;
   PARENT @oDialog ;
   ADDBUTTONS

RETURN

/* --------------------- */

STATIC FUNCTION BrowseCollect ( cAlias, oDialog, oBrowse, aPickField )

LOCAL GetList := {}, i, aChildList

IF Valtype(oBrowse) = 'O'
  aChildList := oBrowse:ChildList()
  FOR i := 1 TO Len(aChildList)
    aChildList[i]:Destroy()
  NEXT
  oBrowse:Destroy()
ENDIF

oBrowse := nil

IF Empty(aPickField)
  RETURN nil
ENDIF

@ 2,40 DCBROWSE oBrowse DATA cAlias SIZE 39,12 PARENT oDialog:drawingArea

SELECT collect
FOR i := 1 TO Len(aPickField)
  DCBROWSECOL DATA &('{||COLLECT->'+aPickField[i]+'}') ;
    HEADER aPickField[i] PARENT oBrowse
NEXT

DCREAD GUI ;
   PARENT oDialog ;
   EXIT

oBrowse:hide()
oBrowse:show()

RETURN nil

Files:

DCPICK.CH

See Also:

   @ DCLISTBOX
   dc_vartolistbox()
   dc_varfromlistbox()


@ DCPRINT BITMAP

Send BitMap to printer using @..SAY style printing

@..DCPRINT BITMAP prints a Bitmap on the page using @..SAY style coordinates. The BitMap may be a resources that has been linked into the program .EXE, a .BMP file or a .JPG file. <br><br>

Syntax:

@ <nSrow>, <nScol> [, <nErow>, <nEcol> ] DCPRINT BITMAP <ncRes> ;
      [PRINTER <oPrinter>] ;
      [AUTOSCALE] ;
      [CENTER] ;
      [SCALE] ;
      [PIXEL] ;
      [WHEN <bWhen>] ;
      [RESTYPE <cResType>] ;
      [RESFILE <cResFile>]

Arguments:

<nSrow>, <nScol>, <nErow>, <nEcol> are the page coordinates
to print the bitmap.  These are row/column text coordinates
unless the PIXEL argument was used with the DCPRINT ON
command, then they are pixel coordinates.  If <nErow> and <nECol>
are not used then the end row and end column will be calculated
from the size of the bitmap times the scale.

<ncRes> is the name of a .BMP file, a .JPG file or the number
of a bitmap resource that has been linked to the application.

PRINTER <oPrinter> is the printer object returned by the
DCPRINT ON command or the DC_Printer() class.  If this clause
is not used then the printer object referenced by
DC_PrinterObject() is the default.

AUTOSCALE will automatically scale the bitmap image to the
coordinates to maintain the aspect ratio.

CENTER will center the bitmap within the coordinates.

SCALE is a numerical value used to scale the size of the bitmap.
The default is 1.  This clause is ignored if all four coordinates
are used.  For example, to print a bitmap two times larger than
the original size use SCALE 2.

PIXEL will cause coordinates NOT to be text-based.  Normally,
coordinates are text-based and are scaled to the coordinate
system defined by the UNITS command.  The scaling is based on
the SIZE clause.

WHEN <bWhen> is a condition codeblock that is evaluated before
the command is executed during previewing and printing from
preview.  The DC_Printer() object is passed to the code block.
The code block must return a logical .TRUE. to enable the command.

RESTYPE <cResType> provides support for bitmap resources of type
BMP, PNG, GIF and JPEG that have been linked into a .RES file to
be used as the caption.

Example:

@ .. DCPUSHBUTTON CAPTION 2000 RESTYPE GIF

// myres.arc
USERDEF GIF
2000 = FILE ".\GIFChart.GIF"

RESFILE <cResFile> is the name of the .DLL that contains the
resource stated in the RESTYPE <cResType> clause.  If this parameter
is not used, then the resource must be in the .EXE.

Examples:

#include "dcprint.ch"

PROCEDURE XTest( lPreview )

LOCAL aFor_Sale, oPrinter, i, nLineCount, cMemo, cMemoLine, cScrn

lPreview := IIF( Valtype(lPreview)='L',lPreview,.t.)

USE collect NEW

aFor_Sale := { 'No','Yes','Not Sure' }

BEGIN SEQUENCE

IF lPreview
  DCPRINT ON SIZE 60,100 TO oPrinter FONT '12.Courier' PREVIEW
ELSE
  DCPRINT ON SIZE 60,100 TO oPrinter FONT '12.Courier'
ENDIF

IF Valtype(oPrinter) # 'O' .OR. !oPrinter:lActive
  BREAK
ENDIF

DC_Gui(.t.)

IF !lPreview
  cScrn := DC_WaitOn()
ENDIF

DO WHILE !Eof()

  @ 2,0,20,45 DCPRINT BITMAP COLLECT->bitmap1
  @ 2,50,20,95 DCPRINT BITMAP COLLECT->bitmap2

  DCPRINT FONT '12.Courier'

  @ 23, 5, 37, 90 DCPRINT BOX

  @ 24,10 DCPRINT SAY '    Description:'
  @ 25,10 DCPRINT SAY '           Type:'
  @ 26,10 DCPRINT SAY '       Sub-Type:'
  @ 27,10 DCPRINT SAY '      Condition:'
  @ 28,10 DCPRINT SAY '       Location:'
  @ 29,10 DCPRINT SAY '      For Sale?:'
  @ 30,10 DCPRINT SAY '  Original Date:'
  @ 31,10 DCPRINT SAY '  Acquired Date:'
  @ 32,10 DCPRINT SAY ' Original Price:'
  @ 33,10 DCPRINT SAY 'Appraised Value:'
  @ 34,10 DCPRINT SAY '       Comments:'
  @ 35,10 DCPRINT SAY '      Bit Map 1:'
  @ 36,10 DCPRINT SAY '      Bit Map 2:'

  DCPRINT FONT '14.Terminal'

  @ 24,32 DCPRINT SAY COLLECT->descrip
  @ 25,32 DCPRINT SAY COLLECT->type
  @ 26,32 DCPRINT SAY COLLECT->sub_type
  @ 27,32 DCPRINT SAY COLLECT->condition
  @ 28,32 DCPRINT SAY COLLECT->location
  @ 29,32 DCPRINT SAY aFor_Sale[COLLECT->for_sale+1]
  @ 30,32 DCPRINT SAY COLLECT->date_orig
  @ 31,32 DCPRINT SAY COLLECT->date_acqu
  @ 32,32 DCPRINT SAY COLLECT->orig_price
  @ 33,32 DCPRINT SAY COLLECT->appr_value
  @ 34,32 DCPRINT SAY COLLECT->comments
  @ 35,32 DCPRINT SAY COLLECT->bitmap1
  @ 36,32 DCPRINT SAY COLLECT->bitmap2

  DCPRINT FONT '12.Arial'

  cMemo := Alltrim(COLLECT->memo)
  nLineCount := MLCount(cMemo)
  FOR i := 1 TO nLineCount - 1
    cMemoLine := MemoLine( cMemo, nil, i )
    IF Empty(cMemoLine)
      EXIT
    ENDIF
    @ 40+i,10 DCPRINT SAY cMemoLine
  NEXT

  DCPRINT EJECT

  SKIP

ENDDO

IF !lPreview
  DC_Impl(cScrn)
ENDIF

END SEQUENCE

DCPRINT OFF

RETURN

Files:

DCPRINT.CH

See Also:


@ DCPRINT BOX

Send Box to printer using @..SAY style printing

@..DCPRINT BOX prints a Box on the page using @..SAY style coordinates.

Syntax:

@ <nSrow>, <nScol>, <nErow>, <nEcol> DCPRINT BOX ;
  [FILL <nFill>] ;
  [HRADIUS <nHRadius>] ;
  [VRADIUS <nVRadius>] ;
  [PRINTER <oPrinter>] ;
  [AREAATTR <aAreaAttr>] ;
  [LINEATTR <aLineAttr>] ;
  [LINEWIDTH <nLineWidth>] ;
  [NOSCALE] [PIXEL] ;
  [WHEN <bWhen>] ;
  [LINECOLOR <anLineColorFG> [,<anLineColorBG>] ;
  [AREACOLOR <anAreaColorFG> [,<anAreaColorBG>] ;
  [GRAY <nGrayPct>]

Arguments:

<nSrow>, <nScol>, <nErow>, <nEcol> are the page coordinates to
print the box.  These are row/column text coordinates unless
the PIXEL argument was used with the DCPRINT ON command,
then they are pixel coordinates.

FILL <nFill> specifies whether the rectangle is drawn as an
outline or is filled.  The following table shows the #define
constants from the GRA.CH file to use for <nFill> :

 Constant         Description

 GRA_FILL         Fills rectangle
 GRA_OUTLINE (*)  Only draws rectangle border
 GRA_OUTLINEFILL  Draws rectangle border and fills

 (*) Default value

 The parameters <nHRad> and <nVRad> determine how much to round
 the corners of the rectangle.  Both are positive integers
 which, taken together, determine the distance (radius of
 curvature) from a corner to the middle o fthe rectangle. This
 distance provides the measure from which the corners are
 rounded. <nHRad> indicates the horizontal distance.  When
 <nHRad> is equal to <nVRad> , the corners are rounded by
 a 90 degree arc.

 PRINTER <oPrinter> is the printer object returned by the
 DCPRINT ON command or the DC_Printer() class.  If this clause
 is not used then the printer object referenced by
 DC_PrinterObject() is the default.

AREAATTR <aAreaAttr> is an array of area attributes.

<aAreaAttr> := Array( GRA_AA_COUNT )

<aAreaAttr> is an array whose elements contain the attributes for
areas later drawn by @..DCPRINT BOX.

 #define constants of the attribute array for areas

 Array element     #define | value  Default value

 GRA_AA_COLOR      GRA_CLR_*        GRA_CLR_NEUTRAL
 GRA_AA_BACKCOLOR  GRA_CLR_*        GRA_CLR_BACKGROUND
 GRA_AA_MIXMODE    GRA_FGMIX_*      GRA_FGMIX_OVERPAINT
 GRA_AA_BGMIXMODE  GRA_BGMIX_*      GRA_BGMIX_LEAVEALONE
 GRA_AA_SYMBOL     GRA_SYM_*        GRA_SYM_SOLID

LINEATTR <aLineAttr> is an array of line attributes.

<aLineAttr> := Array( GRA_AL_COUNT )

<aLineAttr> is an array whose elements contain the attributes for
lines later drawn by @..DCPRINT BOX.

 #define constants of the attribute array for lines

 Array element     #define | value  Default value

 GRA_AL_COLOR      GRA_CLR_*        GRA_CLR_NEUTRAL
 GRA_AL_BACKCOLOR  GRA_CLR_*        GRA_CLR_BACKGROUND
 GRA_AL_MIXMODE    GRA_FGMIX_*      GRA_FGMIX_OVERPAINT
 GRA_AL_BGMIXMODE  GRA_BGMIX_*      GRA_BGMIX_LEAVEALONE
 GRA_AL_SYMBOL     GRA_SYM_*        GRA_SYM_SOLID

HRADIUS <nHRadius> indicates the horizontal distance. When
<nHRadius> is equal to <nVRadius> , the corners are rounded by
a 90o arc.

VRADIUS <nVRadius> determines the vertical curvature radius for
rounding the corners. For rounded corners, both parameters
<nHRadius> and <nVRadius> must be greater than 0.

LINEWIDTH <nLineWidth> is the thickness (in units) of the box
perimeter.  The default is 1.

The parameters <nHRadius> and <nVRadius> determine how much to
round the corners of the rectangle. Both are positive integers
which, taken together, determine the distance (radius of
curvature) from a corner to the middle of the rectangle. This
distance provides the measure from which the corners are
rounded.

NOSCALE or PIXEL will cause coordinates NOT to be text-based.
Normally, coordinates are text-based and are scaled to the
coordinate system defined by the UNITS command.  The scaling is
based on the SIZE clause.

WHEN <bWhen> is a condition codeblock that is evaluated before
the command is executed during previewing and printing from
preview.  The DC_Printer() object is passed to the code block.
The code block must return a logical .TRUE. to enable the command.

LINECOLOR <anLineColorFG>, <anLineColorBG> is the foreground and
background color of the lines that make up the box.  Arguments
may be numeric GRA* values as defined in GRA.CH or an array of
three (3) numeric variables representing the Red, Green and Blue
components of a RGB color (0-255).

AREACOLOR <anAreaColorFG>, <anAreaColorBG> is the foreground and
background color of the area within the box.  Arguments may be
numeric GRA* values as defined in GRA.CH or an array of three (3)
numeric variables representing the Red, Green and Blue components
of a RGB color (0-255).

GRAY <nGrayPct> will gray the area within the box.  For a lighter
gray use a smaller number.  For a darker gray use a larger number.

Examples:

#include "dcprint.ch"

PROCEDURE XTest( lPreview )

LOCAL aFor_Sale, oPrinter, i, nLineCount, cMemo, cMemoLine, ;
      cScrn, aAttr

lPreview := IIF( Valtype(lPreview)='L',lPreview,.t.)

USE collect NEW

aFor_Sale := { 'No','Yes','Not Sure' }

BEGIN SEQUENCE

IF lPreview
  DCPRINT ON SIZE 60,100 TO oPrinter FONT '12.Courier' PREVIEW
ELSE
  DCPRINT ON SIZE 60,100 TO oPrinter FONT '12.Courier'
ENDIF

IF Valtype(oPrinter) # 'O' .OR. !oPrinter:lActive
  BREAK
ENDIF

DC_Gui(.t.)

IF !lPreview
  cScrn := DC_WaitOn()
ENDIF

DO WHILE !Eof()

  @ 2,0,20,45 DCPRINT BITMAP COLLECT->bitmap1
  @ 2,50,20,95 DCPRINT BITMAP COLLECT->bitmap2

  DCPRINT FONT '12.Courier'

  aAttr := Array(GRA_AL_COUNT)
  aAttr[GRA_AL_COLOR] := GRA_CLR_RED
  @ 23, 5, 37, 90 DCPRINT BOX LINEATTR aAttr

  @ 24,10 DCPRINT SAY '    Description:'
  @ 25,10 DCPRINT SAY '           Type:'
  @ 26,10 DCPRINT SAY '       Sub-Type:'
  @ 27,10 DCPRINT SAY '      Condition:'
  @ 28,10 DCPRINT SAY '       Location:'
  @ 29,10 DCPRINT SAY '      For Sale?:'
  @ 30,10 DCPRINT SAY '  Original Date:'
  @ 31,10 DCPRINT SAY '  Acquired Date:'
  @ 32,10 DCPRINT SAY ' Original Price:'
  @ 33,10 DCPRINT SAY 'Appraised Value:'
  @ 34,10 DCPRINT SAY '       Comments:'
  @ 35,10 DCPRINT SAY '      Bit Map 1:'
  @ 36,10 DCPRINT SAY '      Bit Map 2:'

  DCPRINT FONT '14.Terminal'

  @ 24,32 DCPRINT SAY COLLECT->descrip
  @ 25,32 DCPRINT SAY COLLECT->type
  @ 26,32 DCPRINT SAY COLLECT->sub_type
  @ 27,32 DCPRINT SAY COLLECT->condition
  @ 28,32 DCPRINT SAY COLLECT->location
  @ 29,32 DCPRINT SAY aFor_Sale[COLLECT->for_sale+1]
  @ 30,32 DCPRINT SAY COLLECT->date_orig
  @ 31,32 DCPRINT SAY COLLECT->date_acqu
  @ 32,32 DCPRINT SAY COLLECT->orig_price
  @ 33,32 DCPRINT SAY COLLECT->appr_value
  @ 34,32 DCPRINT SAY COLLECT->comments
  @ 35,32 DCPRINT SAY COLLECT->bitmap1
  @ 36,32 DCPRINT SAY COLLECT->bitmap2

  DCPRINT FONT '12.Arial'

  cMemo := Alltrim(COLLECT->memo)
  nLineCount := MLCount(cMemo)
  FOR i := 1 TO nLineCount - 1
    cMemoLine := MemoLine( cMemo, nil, i )
    IF Empty(cMemoLine)
      EXIT
    ENDIF
    @ 40+i,10 DCPRINT SAY cMemoLine
  NEXT

  DCPRINT EJECT

  SKIP

ENDDO

IF !lPreview
  DC_Impl(cScrn)
ENDIF

END SEQUENCE

DCPRINT OFF

RETURN

Files:

DCPRINT.CH

See Also:


@ DCPRINT LINE

Send Line to printer using @..SAY style printing

@..DCPRINT LINE prints a Line on the page using @..SAY style coordinates.

Syntax:

@ <nSrow>, <nScol>, <nErow>, <nEcol> DCPRINT LINE ;
  [ATTRIBUTE <aAttr>] ;
  [NOSCALE] [PIXEL] ;
  [WHEN <bWhen>] ;
  [COLOR <anColorFG> [,<anColorBG>] ;
  [LINEWIDTH <nLineWidth>]

Arguments:

<nSrow>, <nScol>, <nErow>, <nEcol> are the page coordinates to
print the box.  These are row/column text coordinates unless
the PIXEL argument was used with the DCPRINT ON command,
then they are pixel coordinates.

PRINTER <oPrinter> is the printer object returned by the
DCPRINT ON command or the DC_Printer() class.  If this clause
is not used then the printer object referenced by
DC_PrinterObject() is the default.

ATTRIBUTE <aAttr> is an array of attributes.

 <aAttr> := Array( GRA_AL_COUNT )

 <aAttr> is an array whose elements contain the attributes for
 lines drawn by graphic functions.

 #define constants of the attribute array for lines. These
 con stants are defined in GRA.CH.

 Array element   #define group    Default value

 GRA_AL_COLOR    GRA_CLR_*        GRA_CLR_NEUTRAL
 GRA_AL_MIXMODE  GRA_FGMIX_*      GRA_FGMIX_OVERPAINT
 GRA_AL_WIDTH    GRA_LINEWIDTH_*  GRA_LINEWIDTH_NORMAL
 GRA_AL_TYPE     GRA_LINETYPE_*   GRA_LINETYPE_SOLID

NOSCALE or PIXEL will cause coordinates NOT to be text-based.
Normally, coordinates are text-based and are scaled to the
coordinate system defined by the UNITS command.  The scaling is
based on the SIZE clause.

WHEN <bWhen> is a condition codeblock that is evaluated before
the command is executed during previewing and printing from
preview.  The DC_Printer() object is passed to the code block.
The code block must return a logical .TRUE. to enable the command.

COLOR <anColorFG>, <anColorBG> is the foreground and background
color.  Arguments may be numeric GRA* values as defined in GRA.CH
or an array of three (3) numeric variables representing the
Red, Green and Blue components of a RGB color (0-255).

LINEWIDTH <nLineWidth> is the line width in pixels or units.

Examples:

#include "dcprint.ch"

PROCEDURE XTest( lPreview )

LOCAL nRow, nSaveRec, cScrn, aFor_Sale, cFontName, oPrinter, i, nStartRow

USE collect
nSaveRec := RecNo()
GO TOP

aFor_Sale := { 'No','Yes','Not Sure' }

BEGIN SEQUENCE

IF lPreview
  DCPRINT ON SIZE 50,98 FONT '9.Terminal' TO oPrinter PREVIEW
ELSE
  DCPRINT ON SIZE 50,98 FONT '9.Terminal' TO oPrinter
ENDIF

IF Valtype(oPrinter) # 'O' .OR. !oPrinter:lActive
  BREAK
ENDIF

cFontName := oPrinter:GetFontCompoundName()

IF !lPreview
  cScrn := DC_WaitOn('Printing..')
ENDIF

FOR i := 1 TO oPrinter:nCopies

  GO TOP
  nRow := 3
  oPrinter:nPage := 1

  DO WHILE !Eof() .AND. DC_PrinterOk()

    IF nRow <= 3

      DCPRINT FONT '14.Arial.Bold'

      @ nRow-1, 5, nRow+1, 90 DCPRINT BOX

      @ nRow,10 DCPRINT SAY 'My Personal Collection Inventory'
      @ nRow,50 DCPRINT SAY 'Page ' + Alltrim(Str(oPrinter:nPage))
      @ nRow,70 DCPRINT SAY Date()

      nRow += 3
      nStartRow := nRow
      @ nRow+.5, 4, nRow+.5, 94 DCPRINT LINE

      DCPRINT FONT '12.Arial.Bold'

      @ nRow+.5,5  DCPRINT SAY 'Description'
      @ nRow+.5,40 DCPRINT SAY 'Type'
      @ nRow+.5,55 DCPRINT SAY 'Sub-Type'
      @ nRow+.5,70 DCPRINT SAY 'Cond'
      @ nRow+.5,76 DCPRINT SAY 'For Sale?'
      @ nRow+.5,87 DCPRINT SAY 'Value'
      nRow += 2

      DCPRINT FONT cFontName

    ELSE

      @ nRow+.3, 4, nRow+.3, 94 DCPRINT LINE

      @ nRow,5  DCPRINT SAY COLLECT->descrip
      @ nRow,40 DCPRINT SAY COLLECT->type
      @ nRow,55 DCPRINT SAY COLLECT->sub_type
      @ nRow,70 DCPRINT SAY COLLECT->condition
      @ nRow,76 DCPRINT SAY aFor_Sale[COLLECT->for_sale+1]
      @ nRow,87 DCPRINT SAY Str(COLLECT->appr_value,7,2)
      nRow++

      SKIP

      IF nRow > ( oPrinter:nRows - 5 ) .OR. Eof()
        nRow += .5
        nStartRow += .5
        @ nRow, 4, nRow, 94 DCPRINT LINE
        @ nStartRow, 4, nRow, 4 DCPRINT LINE
        @ nStartRow,39, nRow,39 DCPRINT LINE
        @ nStartRow,54, nRow,54 DCPRINT LINE
        @ nStartRow,69, nRow,69 DCPRINT LINE
        @ nStartRow,75, nRow,75 DCPRINT LINE
        @ nStartRow,86, nRow,86 DCPRINT LINE
        @ nStartRow,94, nRow,94 DCPRINT LINE
              DCPRINT EJECT
        nRow := 3
      ENDIF

    ENDIF

  ENDDO

NEXT

END SEQUENCE

DCPRINT OFF

IF !lPreview
  DC_Impl(cScrn)
ENDIF

GO nSaveRec
RETURN nil

Files:

DCPRINT.CH

See Also:


@ DCPRINT MARKER

Send Marker to printer using @..SAY style printing

@..DCPRINT MARKER prints a Marker on the page using @..SAY style coordinates.

Syntax:

@ <nSrow>, <nScol> DCPRINT MARKER ;
  [ATTRIBUTE <aAttr>] ;
  [NOSCALE] [PIXEL] ;
  [WHEN <bWhen>] ;
  [COLOR <anColorFG> [,<anColorBG>]

Arguments:

<nSrow>, <nScol> are the page coordinates to print the marker.
These are row/column text coordinates unless the PIXEL
argument was used with the DCPRINT ON command, then they are
pixel coordinates.

PRINTER <oPrinter> is the printer object returned by the
DCPRINT ON command or the DC_Printer() class.  If this clause
is not used then the printer object referenced by
DC_PrinterObject() is the default.

ATTRIBUTE <aAttr> is an array of attributes.

<aAttr> := Array( GRA_AM_COUNT )

<aAttr> is an array whose elements contain the attributes for
lines drawn by graphic functions.

#define constants of the attribute array for lines. These
constants are defined in GRA.CH.

#define constants for the attribute array of GraMarker()

 Array element     #define | value     Default value

 GRA_AM_COLOR      GRA_CLR_*           GRA_CLR_NEUTRAL
 GRA_AM_BACKCOLOR  GRA_CLR_*           GRA_CLR_BACKGROUND
 GRA_AM_MIXMODE    GRA_FGMIX_*         GRA_FGMIX_OVERPAINT
 GRA_AM_BGMIXMODE  GRA_BGMIX_*         GRA_BGMIX_LEAVEALONE
 GRA_AM_SYMBOL     GRA_MARKSYM_*       GRA_MARKSYM_CROSS
 GRA_AM_BOX        { nXsize, nYsize }  Dependent on output device

NOSCALE or PIXEL will cause coordinates NOT to be text-based.
Normally, coordinates are text-based and are scaled to the
coordinate system defined by the UNITS command.  The scaling is
based on the SIZE clause.

WHEN <bWhen> is a condition codeblock that is evaluated before
the command is executed during previewing and printing from
preview.  The DC_Printer() object is passed to the code block.
The code block must return a logical .TRUE. to enable the command.

COLOR <anColorFG>, <anColorBG> is the foreground and background
color.  Arguments may be numeric GRA* values as defined in GRA.CH
or an array of three (3) numeric variables representing the
Red, Green and Blue components of a RGB color (0-255).

Examples:

#include "dcprint.ch"
#include "gra.ch"

PROCEDURE XTest( lPreview )

// Displays all markers
// The example displays all available markers and
// their #define constants.

LOCAL aAttr, aMarker, i

IF lPreview
  DCPRINT ON PREVIEW
ELSE
  DCPRINT ON
ENDIF
                                    // #define constants as
aMarker:= { ;                       // text and as  values
  { "GRA_MARKSYM_DEFAULT       ", GRA_MARKSYM_DEFAULT        }, ;
  { "GRA_MARKSYM_CROSS         ", GRA_MARKSYM_CROSS          }, ;
  { "GRA_MARKSYM_PLUS          ", GRA_MARKSYM_PLUS           }, ;
  { "GRA_MARKSYM_DIAMOND       ", GRA_MARKSYM_DIAMOND        }, ;
  { "GRA_MARKSYM_SQUARE        ", GRA_MARKSYM_SQUARE         }, ;
  { "GRA_MARKSYM_SIXPOINTSTAR  ", GRA_MARKSYM_SIXPOINTSTAR   }, ;
  { "GRA_MARKSYM_EIGHTPOINTSTAR", GRA_MARKSYM_EIGHTPOINTSTAR }, ;
  { "GRA_MARKSYM_SOLIDDIAMOND  ", GRA_MARKSYM_SOLIDDIAMOND   }, ;
  { "GRA_MARKSYM_SOLIDSQUARE   ", GRA_MARKSYM_SOLIDSQUARE    }, ;
  { "GRA_MARKSYM_DOT           ", GRA_MARKSYM_DOT            }, ;
  { "GRA_MARKSYM_SMALLCIRCLE   ", GRA_MARKSYM_SMALLCIRCLE    }, ;
  { "GRA_MARKSYM_BLANK         ", GRA_MARKSYM_BLANK          }  ;
}

aAttr  := Array( GRA_AM_COUNT )     // create attribute array

FOR i:=1 TO 12

  @ i+10,10 DCPRINT SAY aMarker[i,1]
  aAttr[ GRA_AM_SYMBOL ] := aMarker[i,2]

  @ i+10,50 DCPRINT MARKER ATTR aAttr

NEXT

DCPRINT OFF

RETURN

Files:

DCPRINT.CH

See Also:


@ DCPRINT RTF

Send RTF text to printer using @..SAY style printing

@..DCPRINT RTF prints a RTF text on the page using @..SAY style coordinates.

Syntax:

@ <nSrow>, <nScol> [, <nErow>, <nEcol> ] DCPRINT RTF <cRtf> ;
      [PRINTER <oPrinter>] ;
      [PIXEL] ;
      [WHEN <bWhen>]

Arguments:

<nSrow>, <nScol>, <nErow>, <nEcol> are the page coordinates
to print the text.  These are row/column text coordinates
unless the PIXEL argument was used with the DCPRINT ON
command, then they are pixel coordinates.  If <nErow> and <nECol>
are not used then the end row and end column will be calculated.

<cRtf> is a variable containing the RTF text to print.

PRINTER <oPrinter> is the printer object returned by the
DCPRINT ON command or the DC_Printer() class.  If this clause
is not used then the printer object referenced by
DC_PrinterObject() is the default.

PIXEL will cause coordinates NOT to be text-based.  Normally,
coordinates are text-based and are scaled to the coordinate
system defined by the UNITS command.  The scaling is based on
the SIZE clause.

WHEN <bWhen> is a condition codeblock that is evaluated before
the command is executed during previewing and printing from
preview.  The DC_Printer() object is passed to the code block.
The code block must return a logical .TRUE. to enable the command.

Files:

DCPRINT.CH

See Also:

   @ DCRTF


@ DCPRINT SAY

Send text to printer using @..SAY style printing

@..DCPRINT SAY prints text at a specified row and column.

Syntax:

[ @ <nRow>, <nCol> ] DCPRINT SAY <uText> ;
   [PICTURE <cPicture>] ;
   [FONT <ocFont> [CODEPAGE <nCodePage>] ] ;
   [PRINTER <oPrinter>] ;
   [FIXED] ;
   [NOSCALE] [PIXEL] ;
   [ATTRIBUTE <aAttr>] ;
   [ALIGN <nAlign>] ;
   [OUTLINE] ;
   [WHEN <bWhen>] ;
   [WIDTH <nWidth>] ;
   [COLOR <anColorFG> [,<anColorBG>]

Arguments:

<uText> is any variable.

<nRow>, <nCol> are the start page coordinates to print the
text.  These are row/column text coordinates unless the
NOSCALE or PIXEL parameter was used in the DCPRINT ON command
or the NOSCALE or PIXEL argument is used with to the @..DCPRINT SAY
command.

NOSCALE or PIXEL will cause coordinates NOT to be text-based.
Normally, coordinates are text-based and are scaled to the
coordinate system defined by the UNITS command.  The scaling is
based on the SIZE clause.

If <nRow> and <nCol> arguments are not used then the text will
be printed at the current pen location which is usually the end
of the last item printed by @..DCPRINT SAY.  This is desirable
when printing concatenated text with changes in color or changes
in font.

FONT <ocFont> is the font to use.  This may be a font object or
a character string containing the font compound name.  If no
font clause is used, then the font selected by the DCPRINT FONT
clause will be the default.

 NOTE: To print with UNDERSCORE, use the word "Underscore" in
       the FONT clause. ex: "12.Arial Bold Underscore".

CODEPAGE <nCodePage> is the desired code page to use with the
prescribed font other than the default code page.

PICTURE <cPicture> is any picture clause that conforms to the
specification defined in the Xbase++ documentation for the
TRANSFORM() function.

FIXED will print each character of the string on the grid
defined by the SIZE command of the DCPRINT ON command.  FIXED
should be used for numeric columns and strings used as heading
separators like '-------'.

PRINTER <oPrinter> is the printer object returned by the
DCPRINT ON command or the DC_Printer() class.  If this clause
is not used then the printer object referenced by
DC_PrinterObject() is the default.

ATTRIBUTE <aAttr> is an array of attributes that meets the
specification for string attributes such as color, mixmode,
alignment, etc.

<aAttr> := Array( GRA_AS_COUNT )

<aAttr> is an array whose elements contain the attributes for
character strings drawn by the function GraStringAt().

#define constants of the attribute array for character strings.
  These contants are defined in GRA.CH.

 Array element       #define | value     Default value

 GRA_AS_COLOR        GRA_CLR_*           GRA_CLR_NEUTRAL
 GRA_AS_BACKCOLOR    GRA_CLR_*           GRA_CLR_BACKGROUND
 GRA_AS_MIXMODE      GRA_FGMIX_*         GRA_FGMIX_OVERPAINT
 GRA_AS_BGMIXMODE    GRA_BGMIX_*         GRA_BGMIX_LEAVEALONE
 GRA_AS_BOX          { nXsize, nYsize }  dependent on output device
 GRA_AS_ANGLE        { nX, nY }          { 1, 0 }
 GRA_AS_SHEAR        { nX, nY }          { 0, 1 }

 GRA_AS_DIRECTION    GRA_CHDIRN_*        GRA_CHDIRN_LEFTRIGHT
 GRA_AS_HORIZALIGN   GRA_HALIGN_*        GRA_HALIGN_LEFT
 GRA_AS_VERTALIGN    GRA_VALIGN_*        GRA_VALIGN_BASE
 GRA_AS_EXTRA        nExtra              0
 GRA_AS_BREAK_EXTRA  nBreakExtra         0

ALIGN <nAlign> is used to justify the text left, center or right
both vertically and horizontally around the specified <nRow> and
<nCol> coordinates.  <nAlign> is a summation of define manifest
constants from DCPRINT.CH:

  Constant               Description
  ---------------------- --------------------------------------
  DCPRINT_ALIGN_LEFT     Justify Left (Default)
  DCPRINT_ALIGN_BOTTOM   Justify Bottom (Default)
  DCPRINT_ALIGN_RIGHT    Justify Right
  DCPRINT_ALIGN_HCENTER  Justify Horizontally Centered
  DCPRINT_ALIGN_TOP      Justify Top
  DCPRINT_ALIGN_VCENTER  Justify Vertically Centered

OUTLINE will draw a box around the text.

            Ex: @ 10,10 DCPRINT SAY 'Testing' ;
                  ALIGN DCPRINT_ALIGN_CENTER + DCPRINT_ALIGN_VCENTER

WHEN <bWhen> is a condition codeblock that is evaluated before
the command is executed during previewing and printing from
preview.  The DC_Printer() object is passed to the code block.
The code block must return a logical .TRUE. to enable the command.

WIDTH <nWidth> will truncate the <uText> to fit within the
specified width.

COLOR <anColorFG>, <anColorBG> is the foreground and background
color.  Arguments may be numeric GRA* values as defined in GRA.CH
or an array of three (3) numeric variables representing the
Red, Green and Blue components of a RGB color (0-255).

Notes:

The @..DCPRINT SAY command uses the :AtSay() method of the printer object. This method looks at the current ::nPage instance variable and compares it to the ::nFrom value and the ::nTo value. If the current page is outside the range selected by the user, then no output will be sent to the printer.

Examples:

#include "dcprint.ch"

PROCEDURE XTest( lPreview )

LOCAL aFor_Sale, oPrinter, i, nLineCount, cMemo, cMemoLine, cScrn

lPreview := IIF( Valtype(lPreview)='L',lPreview,.t.)

USE collect NEW

aFor_Sale := { 'No','Yes','Not Sure' }

BEGIN SEQUENCE

IF lPreview
  DCPRINT ON SIZE 60,100 TO oPrinter FONT '12.Courier' PREVIEW
ELSE
  DCPRINT ON SIZE 60,100 TO oPrinter FONT '12.Courier'
ENDIF

IF Valtype(oPrinter) # 'O' .OR. !oPrinter:lActive
  BREAK
ENDIF

DC_Gui(.t.)

IF !lPreview
  cScrn := DC_WaitOn()
ENDIF

DO WHILE !Eof()

  @ 2,0,20,45 DCPRINT BITMAP COLLECT->bitmap1
  @ 2,50,20,95 DCPRINT BITMAP COLLECT->bitmap2

  DCPRINT FONT '12.Courier'

  @ 23, 5, 37, 90 DCPRINT BOX

  aAttr := Array(GRA_AS_COUNT)
  aAttr[GRA_AS_COLOR] := GRA_CLR_BLUE

  @ 24,10 DCPRINT SAY '    Description:' ATTR aAttr
  @ 25,10 DCPRINT SAY '           Type:'
  @ 26,10 DCPRINT SAY '       Sub-Type:'
  @ 27,10 DCPRINT SAY '      Condition:'
  @ 28,10 DCPRINT SAY '       Location:'
  @ 29,10 DCPRINT SAY '      For Sale?:'
  @ 30,10 DCPRINT SAY '  Original Date:'
  @ 31,10 DCPRINT SAY '  Acquired Date:'
  @ 32,10 DCPRINT SAY ' Original Price:'
  @ 33,10 DCPRINT SAY 'Appraised Value:'
  @ 34,10 DCPRINT SAY '       Comments:'
  @ 35,10 DCPRINT SAY '      Bit Map 1:'
  @ 36,10 DCPRINT SAY '      Bit Map 2:'

  DCPRINT FONT '14.Terminal'

  @ 24,32 DCPRINT SAY COLLECT->descrip
  @ 25,32 DCPRINT SAY COLLECT->type
  @ 26,32 DCPRINT SAY COLLECT->sub_type
  @ 27,32 DCPRINT SAY COLLECT->condition
  @ 28,32 DCPRINT SAY COLLECT->location
  @ 29,32 DCPRINT SAY aFor_Sale[COLLECT->for_sale+1]
  @ 30,32 DCPRINT SAY COLLECT->date_orig
  @ 31,32 DCPRINT SAY COLLECT->date_acqu
  @ 32,32 DCPRINT SAY COLLECT->orig_price
  @ 33,32 DCPRINT SAY COLLECT->appr_value
  @ 34,32 DCPRINT SAY COLLECT->comments
  @ 35,32 DCPRINT SAY COLLECT->bitmap1
  @ 36,32 DCPRINT SAY COLLECT->bitmap2

  DCPRINT FONT '12.Arial'

  cMemo := Alltrim(COLLECT->memo)
  nLineCount := MLCount(cMemo)
  FOR i := 1 TO nLineCount - 1
    cMemoLine := MemoLine( cMemo, nil, i )
    IF Empty(cMemoLine)
      EXIT
    ENDIF
    @ 40+i,10 DCPRINT SAY cMemoLine
  NEXT

  DCPRINT EJECT

  SKIP

ENDDO

IF !lPreview
  DC_Impl(cScrn)
ENDIF

END SEQUENCE

DCPRINT OFF

RETURN

Files:

DCPRINT.CH

See Also:

   @ DCRIGHTPRINT SAY
   DCPRINT ON


@ DCPROGRESS

Create a PROGRESS BAR object for displaying with GUI reader

The command @..DCPROGRESS creates a new Progress-Bar object and adds the object to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> @..DCPROGRESS objects are used in combination with the DC_GETPROGRESS() function to update a progress bar for any kind of operation, ie, database indexing, updating, exporting, searching, etc.<br><br> @..DCPROGRESS objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCSTATIC, @..DCBUTTON, @..DCCHECKBOX or @..DCTABPAGE.<br><br>

Syntax:

#command  @ <nRow>,<nCol> DCPROGRESS <oProgress> ;
    [SIZE <nWidth> [,<nHeight>]] ;
    [TYPE <nType>] ;
    [PARENT <oParent>] ;
    [PARENTID <cParentId>] ;
    [PRESENTATION <aPres>] ;
    [COLOR <bncFgC> [,<ncBgC>]] ;
    [PERCENT] ;
    [PERCENTCOLOR <nPercentColor>] ;
    [FONT <ocFont>] ;
    [RADIUS <nRadius>] ;
    [OUTLINE] ;
    [DYNAMIC] ;
    [VERTICAL] ;
    [EVERY <nCount>] ;
    [MAXCOUNT <nMaxCount>] ;
    [TOOLTIP <bcToolTip>] ;
    [HIDE <bHide>] ;
    [CARGO <xCargo>] ;
    [PREEVAL <bPreEval>] ;
    [EVAL <bEval>] ;
    [PIXEL] ;
    [RELATIVE <oRel> ] ;
    [ID <cId>] ;
    [TITLE <cTitle>] ;
    [VISIBLE] ;
    [INVISIBLE] ;
    [GROUP <cGroup>] ;
    [RESIZE <aResize>] ;
    [DRAG <bDrag> [DIALOG <bDD>] ;
    [DROP <bDrop> [CURSOR <nDropCursor>] ;
    [SUBCLASS <cSubClass>]

Arguments:

<nRow> and <nCol> are the row and column of the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE <oRel> argument is
used.  If no parent is assigned, then the parent is the Dialog
box.  IF the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel mode by
including PIXEL as a command argument.

<oProgress> is the name of a local variable to assign to this
object.  This variable is passed to DC_GetProgress() to update
the progress bar.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

SIZE <nWidth>,<nHeight> is the width and height of the
Progress Bar.  If the PIXEL option is set to .TRUE. in DCGET
OPTIONS, then the numbers are in pixels otherwise they are
in standard text-based numbers.

TYPE <nType> is the style of XbpStatic() box to use for the
progress bar.  The default is XBPSTATIC_TYPE_RAISEDBOX.  The
constants for static types are contained in XBP.CH.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.  If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the multiline object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.

The PERCENT clause will paint a small box in the center of the
progress bar for displaying the percentage of progress.

PERCENTCOLOR <nColor> sets the foreground color of the percent
text.  The default is GRA_CLR_BLACK.

FONT <cFont> sets the font of the percent text.

RADIUS <nRadius> sets the radius of the corners of the progress
bar.  The default is 0 (square corners).

The OUTLINE clause will paint a black outline around the progress
bar.

The DYNAMIC clause will cause the display of the percentage to
move dynamically, centered within the colored area of the progress
bar.

The VERTICAL clause will cause the progress bar to progress in
vertically from to bottom to the top, otherwise it will progress
horizontally from left to right.

EVERY <nCount> determines how often the progress bar is updated.

MAXCOUNT <nMaxCount> is a numeric value equal to the maximum
value of the progress bar.  For example, if stepping through a
database, this value would be RECCOUNT().

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

COLOR <ncFGc>, <ncBGc> are foreground and background colors.
They may be character strings representing valid text-based
colors supported by SetColor() or they may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH. If <bncFGc> is a
code block is must return a 2-element array containing a
foreground and background color.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TOOLTIP <bcToolTip> is a character string which will display
as a "Tool Tip" next to the object when the cursor is passed
over the object.  If <bcToolTip> is a code-block, it must return
a character string.  NOTE: The Tooltip painting method is run in
another thread, therefore the codeblock should not run code that
points to the current work area.  It may however, contain
local, public or private variables.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.
The object is passed as a parameter to the code block.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS.

RESIZE <aResize> is an optional array of two (2) elements
used for resizing and repositioning the object when the parent
is resized.

NOTE: RESIZE is to be used in conjunction with the RESIZE clause
      of DCGETOPTIONS. See the RESIZE clause of DCGETOPTIONS for
      examples.

DRAG <bDrag> is a codeblock to evaluate when the left mouse button
is clicked in the object and the drag is started.  The return
value of the code block will be stored in memory to be later
retrieved by the Drop operation. A pointer to the clicked on
object is passed to the code block.

DIALOG <bDD> is a codeblock that will evaluate when the drag is
started.  This is used to call a function that will create a
dialog window which will move with the mouse during the drag.
The dialog window will be destroyed upon the drop operation
or the release of the mouse.

Ex: DRAG {|o|o:getData()} DIALOG {|mp1,mp2,oXbp|DragDialog(mp1,mp2,oXbp)} ;

DROP <bDrop> is a codeblock to evaluate when the left mouse button
is released in the object and the drag is ended.  A pointer to
the object and the value stored in memory at the start of the
Drag are passed to the code block.

CURSOR <nDropCursor> is the mouse cursor that will show when it
is moved over this object during a drag operation.

Ex: DROP {|o,x|o:setData(x),o:invalidateRect()} ;
       CURSOR CURSOR POINTER_DATADROP_ASSIGN

SUBCLASS <cSubClass> is a string containing a class name that
will be used to create the class, rather than DC_XbpProgressBar().
This class should inherit from DC_XbpProgressBar().
See the example in \exp19\samples\subclass.

Notes:

The object created by @ DCPROGRESS is an object of the XbpStatic() class, therefore it can be manipulated with any iVar or method supported by XbpStatic().

Examples:

#include 'dcdialog.ch'
#include 'xbp.ch'
#include 'gra.ch'

PROCEDURE XTest()

LOCAL Getlist := {}, oProgress, oDialog

USE customer

@ 2,5 DCSAY 'Exporting Data to JUNK.DBF'

@ 4,5 DCPROGRESS oProgress ;
       SIZE 60,1.5 ;
       MAXCOUNT RecCount();
       COLOR GRA_CLR_BLUE ;
       PERCENT ;
       EVERY Int(RecCount()/100)

DCREAD GUI TITLE 'My Test Dialog' ;
   PARENT @oDialog ;
   FIT ;
   EXIT

oDialog:show()

COPY TO junk WHILE _Progress( oProgress )

DC_Gui(.t.)
DC_MsgBox('Done')

oDialog:Destroy()

RETURN

/* ----------------- */

STATIC FUNCTION _Progress ( oProgress )

DC_GetProgress( oProgress, CUSTOMER->(RecNo()) )

RETURN .t.

Files:

DCDIALOG.CH

See Also:

   DC_GetProgress()


@ DCPUSHBUTTON

Create a PUSHBUTTON for displaying with GUI reader

The command @..DCPUSHBUTTON creates a new PushButton object and adds the object to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> @..DCPUSHBUTTON objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCRADIO, @..DCMULTILINE, @..DCCHECKBOX or @..DCTABPAGE.

Syntax:

@ <nRow>, <nCol> DCPUSHBUTTON ;
    [CAPTION <bcnoCaption>] ;
    [SIZE <nWidth>, <nHeight>] ;
    [FANCY] ;
    [ACTION <bAction>] ;
    [WHEN <bWhen>] ;
    [HIDE <bHide>  ;
    [PARENT <oParent>] ;
    [PARENTID <cParentID>] ;
    [COLOR <bncFgC> [,<ncBgC>]] ;
    [HELPCODE <cHelpCode>] ;
    [FONT <bocFont>] ;
    [PRESENTATION <aPres>] ;
    [PIXEL] ;
    [OBJECT <oObject>] ;
    [TOOLTIP <bcToolTip>] ;
    [MESSAGE <bcMsg> [INTO <oMsgBox>]] ;
    [CURSOR <naCursor>] ;
    [CARGO <xCargo>] [CARGO "CANCEL"] ;
    [PREEVAL <bPreEval>] ;
    [EVAL <bEval>] ;
    [RELATIVE <oRel>] ;
    [ID <cId>] ;
    [TITLE <cTitle>] ;
    [ACCELKEY <anAccel>] ;
    [GOTFOCUS <bGotFocus>] ;
    [LOSTFOCUS <bLostFocus>] ;
    [TABSTOP] ;
    [NOTABSTOP] ;
    [TABGROUP <nTabGroup>] ;
    [VISIBLE] ;
    [INVISIBLE] ;
    [GROUP <cGroup>] ;
    [STATIC] * ;
      [FOCUSCOLOR <nTextColor> [,<nFrameColor>]] * ;
      [BITMAP <xBMUp> [,<xBMDown> [,<xBMNeutral> [,<xBMFlash>]]]] * ;
      [REGION <aRegion>] * ;
      [FLASH <nFlashIterations> [,<nFlashDelay>]] ;
    [RESIZE <aResize> [SCALEFONT] ] ;
    [RESTYPE <cResType>] ;
    [RESFILE <cResFile>] ;
    [ALIGNCAPTION <nAlign>] ;
    [SOUND <cSound>] ;
    [SCALEBITMAP] ;
    [DRAG <bDrag> [DIALOG <bDD>] ;
    [DROP <bDrop> [CURSOR <nDropCursor>] ;
    [SUBCLASS <cSubClass>]

  * Supported by eXPress++ 1.7 or later

Arguments:

<nRow> and <nCol> are the row and column of the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE argument is used.
If no parent is assigned, then the parent is the Dialog box.
IF the PIXEL option is set to .TRUE. in DCGETOPTIONS, then
the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel
mode by including PIXEL as a command argument.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

CAPTION <bcnoCaption> is the part of the PushButton object that
is displayed within the area of the pushbutton. The caption may
be one of the following:

1) A character string.  An ampersand (&) preceding a character in
   the text assigns the ALT-<char> key as a hotkey for the
   pushbutton and underlines the character.  A tilde (~) preceding
   the character will only underline the character and will not
   enable the hot-key.  A tilde (~) could be used with the
   ACCELKEY clause to establish the hot key(s).

2) A bitmap resource. The numeric resource ID of the bitmap is
   assigned to the instance variable.  If a resource ID is used,
   it must be defined in a resource file that is linked to the
   EXE file using the resource compiler.

3) A bitmap object created with the XbpBitMap() class. (Xbase++
   1.7 or later).

4) A two-element array.  This array must contain either two
   character strings, two bitmap objects or two bitmap numeric
   values.  The first value is the caption to use when the
   pushbutton is "enabled" by the WHEN clause.  The second value
   is the caption to use when the pushbutton is "disabled" by
   the WHEN clause.

4. A code block.  A code block is evaluated whenever the
   DC_GetRefresh() function is called.  This is used to change
   the caption dynamically after the pushbutton object is created.
   The code block must return either a character string, a bitmap
   numeric resource, a bitmap object or an array of 2 elements.

SIZE <nWidth>,<nHeight> is the width and height of the
PushButton.  If the PIXEL option is set to .TRUE. in DCGET
OPTIONS, then the numbers are in pixels otherwise they are
in standard text-based numbers.

FANCY will cause the button to be displayed in a special mode
in which the button will be displayed only as a caption on the
parent object until the mouse is passed over the caption which
will then display the raised button.  DC_FancyButtonMode(1) can
be used to override this clause and force normal buttons.
CAUTION: FANCY cannot be used with a caption that is a bitmap
object, however it can be used with a caption that is a bitmap
resource.

ACTION <bAction> is a codeblock that is to be evaluated
when the pushbutton is activated.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.  If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

OBJECT <oObject> is the name of the memory variable to assign to
this object.

FONT <cFont> is a character string defining an optional font.
The font string must conform to the Xbase++ standard, ie.
"10.Courier Bold". It may also be a font object or a code block
that returns a character string or a font object to later
refresh with DC_GetRefresh().

MESSAGE <bcMsg> is the message you want to display in the
message area of the dialogue screen defined by the DCMESSAGEBOX
command when the object is in focus.  Optionally, INTO <oMsgBox>
will designate which message box to display the message into.
If the INTO clause is not used, then the last message box in the
GetList is the default. <oMsgBox> may also be any object that
supports the :setCaption() method.If <bcMsg> is a code-block,
it must return a character string.

HELPCODE <cHelp> is a character string that is passed to the
DC_HelpF1() function if F1 is pressed or the HELP button
is clicked when this object has focus.  This HELPCODE allows
the Help system to override the passing of the Procedure and
Varname for more specific context-help.

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the pushbutton object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.

TOOLTIP <bcToolTip> is a character string which will display
as a "Tool Tip" next to the object when the cursor is passed
over the object. A semi-colon within the text indicates a new
line.  If <bcToolTip> is a code-block, it must return a character
string.  NOTE: The Tooltip painting method is run in another
thread, therefore the codeblock should not run code that points
to the current work area.  It may however, contain local, public
or private variables.

CURSOR <naCursor> may be either a numeric value or an array of
3 elements which defines an optional mouse pointer to use for
this object.  System mouse pointers start with
XBPWINDOW_POINTERTYPE_ and are defined in XPB.CH.  The default
pointer is XBPWINDOW_POINTERTYPE_POINTER.  <naCursor> may be a
numeric resource ID that points to a Bit-Map that has been
compiled with the resource compiler and linked to the .EXE.
<naCursor> may be a 3-element array described as follows:

  Element  Type  Description
  -------  ---- ---------------------------------------------
    [1]      C   Optional name of .DLL containing the pointer
                 resource.

    [2]      N   The numeric resource ID of the pointer.  If
                 element 1 is a NIL, then this resource must be
                 linked into the .EXE.

    [3]      N   The type of resource as defined in XBP.CH.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

Use the clause CARGO 'CANCEL' if the pushbutton is to be used
to exit a dialog without testing validations.  This will insure
that if the pushbutton is clicked while in a DCGET with a
validation the validation code block will not be evaluated.

COLOR <ncFGc>, <ncBGc> are foreground and background colors.
They may be character strings representing valid text-based
colors supported by SetColor() or they may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH. If <bncFGc> is a
code block is must return a 2-element array containing a
foreground and background color.  The COLOR clause is supported
only when using the STATIC clause.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the object will be disabled and grayed.
If the value returned is .TRUE. then the object will be enabled.
The object is passed as a parameter to the code block.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.
The object is passed as a parameter to the code block.

ACCELKEY <anAccel> is a numeric "hot-key" assignment that will set
focus to the pushbutton object and activate its associated code block
when the hot-key is pressed.  The key must be a valid key with
the prefix xbeK_*.  These keys are defined in APPEVENT.CH.
<anAccel> may also be an array of numeric values to assign more
than one key to the object.

GOTFOCUS <bGotFocus> is a code block that is evaluated when this
object receives input focus.  <bGotFocus> := {|uNIL1,uNIL2,self|...}

LOSTFOCUS <bLostFocus> is a code block that is evaluated when this
object loses input focus.  <bLostFocus> := {|uNIL1,uNIL2,self|...}

TABSTOP will cause the object (Xbase Part) to be set when using
the Tab key.  Note: When logical groups are defined in a dialog
using TABGROUP <nTabGroup>, TABSTOP is usually set to .T. (true)
for the first dialog element in the group.  This allows the first
dialog element of a group to be activated using the Tab key.

NOTABSTOP will cause the object (Xbase Part) to be ignored when
using the Tab key. This clause is needed only to override any
default setting of TabStop by the DCGETOPTIONS [TABSTOP] command.

TABGROUP <nTabGroup> allows objects (Xbase Parts) that are created
immediately after one another in the GetList to be combined into
logical groups. This allows the user to navigate within a dialog
from group to group by pressing the Tab key.  Within a group of
dialog elements navigation is performed using the cursor keys.

Only constants defined in the XBP.CH file can be used as values
for this instance variable.  The following table lists the
available constants:

#define constants for <nTabGroup>:

 Constant             Description

 XBP_NO_GROUP     *)  Dialog element does not belong to a group
 XBP_BEGIN_GROUP      Dialog element is the first in a group
                      (this begins the definition of the group)
 XBP_WITHIN_GROUP     Dialog element is within a group
 XBP_END_GROUP        Dialog element is the last in a group
                      (this ends the definition of the group)

*) Default value

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS.

The following options are supported by eXPress++ 1.7 or later:

When the STATIC * clause is used, a class created from the
XbpDialog() class is used instead of the XbpPushButton() class.
This allows for the creation of complex pushbuttons by allowing
the pushbutton object to be a parent for any other object such
as DCSTATIC or DCSAY for the display of text, icons, bitmaps
etc. on the button.

FOCUSCOLOR * is used to determine the color of any text on the
button when it receives focus by passing the mouse over the button.
<anTextColor> is the color of the text.  If this argument is a
NIL the text color will not be changed.  <anFrameColor> is the
color of a frame that is drawn around the perimeter of the button
to hilight the button when it receives focus.  If this argument
is a NIL, there will be no frame drawn.  These arguments may be
be a numeric color defined by GRA_CLR_* in GRA.CH or a 3 element
array of RGB colors.

BITMAP * <xBMUp> is the background bitmap for the button in the
UP (unpressed) condition.  <xBMDown> is the background bitmap for
the button in the DOWN (pressed) condition and <xBMNeutral> is the
background bitmap of the button in the NEUTRAL (fancy button)
condition.  <xBMFlash> is the bitmap to be used with the FLASH
clause.  Each bitmap will be replicated over the entire pushbutton
background area.  The bitmaps may be numeric resources,
XbpBitMap() objects, or character strings containing a .BMP, .GIF,
or .JPG file name.

FLASH is used with the <xBMFlash> bitmap.  This bitmap will flash
on just before the action block is evaluated.  This feature is for
touch-screen applications or other applications where some kind of
tactile feedback is desired to indicate to the user that the button
has been pressed.  <nFlashIterations> is the number of times that
the bitmap should flash.  <nFlashDelay> is the amount of delay in
100th/second between flashes.

REGION <aRegion> is an array defining the region of the button
to display.  All other areas will be removed.  <aRegion> may be
an array that is created by DC_RegionArray() or may be any other
multidimensional array containing a set of rectangular regions.
<aRegion> is used to display the button as a circle, ellipse,
octagon, diamond, or other irregular shape.

RESIZE <aResize> is an optional array of two (2) elements
used for resizing and repositioning the object when the parent
is resized.

NOTE: RESIZE is to be used in conjunction with the RESIZE clause
      of DCGETOPTIONS. See the RESIZE clause of DCGETOPTIONS for
      examples.

      The optional SCALEFONT clause will automatically scale the
      font size up or down when the object is resized.

RESTYPE <cResType> provides support for bitmap resources of type
BMP, PNG, GIF and JPEG that have been linked into a .RES file to
be used as the caption.

Example:

@ .. DCPUSHBUTTON CAPTION 2000 RESTYPE GIF

// myres.arc
USERDEF GIF
2000 = FILE ".\GIFChart.GIF"

RESFILE <cResFile> is the name of the .DLL that contains the
resource stated in the RESTYPE <cResType> clause.  If this parameter
is not used, then the resource must be in the .EXE.

ALIGNCAPTION <nAlign> is a set of options to use to align the text
on the PushButton.  The options are numerical definitions
starting with BS_* and are defined in DCDIALOG.CH.

Note the most common option is BS_MULTILINE.

SOUND <cSound> is the name of a .WAV file to play when the button
is clicked.

SCALEBITMAP will shrink or enlarge a bitmap caption to fit
exactly within the button size.  Note: bitmaps should be 24-bit
(hi-color) for this to work correctly.

DRAG <bDrag> is a codeblock to evaluate when the left mouse button
is clicked in the object and the drag is started.  The return
value of the code block will be stored in memory to be later
retrieved by the Drop operation. A pointer to the clicked on
object is passed to the code block.

DIALOG <bDD> is a codeblock that will evaluate when the drag is
started.  This is used to call a function that will create a
dialog window which will move with the mouse during the drag.
The dialog window will be destroyed upon the drop operation
or the release of the mouse.

Ex: DRAG {|o|o:getData()} DIALOG {|mp1,mp2,oXbp|DragDialog(mp1,mp2,oXbp)} ;

DROP <bDrop> is a codeblock to evaluate when the left mouse button
is released in the object and the drag is ended.  A pointer to
the object and the value stored in memory at the start of the
Drag are passed to the code block.

CURSOR <nDropCursor> is the mouse cursor that will show when it
is moved over this object during a drag operation.

Ex: DROP {|o,x|o:setData(x),o:invalidateRect()} ;
       CURSOR CURSOR POINTER_DATADROP_ASSIGN

SUBCLASS <cSubClass> is a string containing a class name that
will be used to create the class, rather than DC_XbpPushButton().
This class should inherit from DC_XbpPushButton().
See the example in \exp19\samples\subclass.

Notes:

If the STATIC clause is not used, the object created by @ DCPUSHBUTTON is an object of the XbpPushButton() class, therefore it can be manipulated with any iVar or method supported by XbpPushButton() class.

If the STATIC clause is used, the object created by @ DCPUSHBUTTON is an object of the XbpDialog() class, therefore it can be manipulated with any iVar or method supported by the XbpDialog() class (eXPress++ version 1.7 or later).

Use the clause CARGO 'CANCEL' if the pushbutton is to be used to exit a dialog without testing validations. This will insure that if the pushbutton is clicked while in a DCGET with a validation the validation code block will not be evaluated.

For an example of STATIC buttons, run XDEMO.EXE (sample group 5).

The function DC_BitmapTransparentColor() may be used to set the default transparent color for pushbuttons that have bitmaps as captions.

Examples:

#include "dcdialog.ch"

PROCEDURE Xtest()

LOCAL GetList := {}

@ 5,10 DCPUSHBUTTON CAPTION 'Save to Dictionary' ;
  SIZE 20,2 ;
  ACTION {||SaveToDictionary()}

@ 5,40 DCPUSHBUTTON CAPTION 'Save to Source Code' ;
  SIZE 20,2 ;
  ACTION {||SaveToSource()}

@ 8,10 DCPUSHBUTTON CAPTION 'Make a Backup file' ;
  SIZE 20,2 ;
  ACTION {||MakeBackup()}

@ 8,40 DCPUSHBUTTON CAPTION 'Pack the File' ;
  SIZE 20,2 ;
  ACTION {||PackFile()}

DCREAD GUI ;
   TITLE 'Pushbutton Demo' ;
   ADDBUTTONS ;
   FIT

RETURN

/* -------------------- */

STATIC PROCEDURE SaveToDictionary()

DC_MsgBox('Data has been saved to Dictionary')

RETURN

/* -------------------- */

STATIC PROCEDURE SaveToSource()

DC_MsgBox('Data has been saved to Source Code')

RETURN

/* -------------------- */

STATIC PROCEDURE MakeBackup()

DC_MsgBox('Backup is complete')

RETURN

/* -------------------- */

STATIC PROCEDURE PackFile()

DC_MsgBox('Pack is complete')

RETURN

Files:

DCDIALOG.CH

See Also:

   @ DCTOOLBAR
   @ DCPUSHBUTTONXP
   dc_fancybuttonmode()
   dc_regionarray()


@ DCPUSHBUTTONXP

Create a XP-Style PUSHBUTTON for displaying with GUI reader

The command @..DCPUSHBUTTONXP creates a new XP-Style PushButton object and adds the object to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> @..DCPUSHBUTTONXP objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCRADIO, @..DCMULTILINE, @..DCCHECKBOX or @..DCTABPAGE.

Syntax:

@ <nRow>, <nCol> DCPUSHBUTTONXP ;
    [CAPTION <xCaption> [OFFSET <nCapOffset>]] ;
    [BITMAP <xBitMap> [ALIGN <nBMAlign>] [OFFSET <nBMOffset>] [SCALE <nBmpScale>]] ;
    [CAPTIONARRAY <aCaptions>] ;
    [SIZE <nWidth>, <nHeight>] ;
    [ACTION <bAction>] ;
    [MENUACTION <bMenuAction>] ;
    [TILEBITMAP <xTile>] ;
    [COLOR <bncFgC> [,<ncBgC>]] ;
    [MOUSECOLOR <ncFGCMouse> [,<ncBgCMouse>]] ;
    [MOUSESOUND <abMouseSound>] ;
    [MOUSESCALE <nMouseScale>] ;
    [MOUSEFONT <cMouseFont>] ;
    [DISABLEDCOLOR <nDisabledBGColor> [,<nDisabledFGColor>]] ;
    [GRAYBITMAP] ;
    [CLICKCOLOR <ncFgCClick> [,<ncBgCClick>>] ;
    [GRADIENT <nGradStep> [REVERSE] [STYLE <nGradStyle>] [LEVEL <nGradLevel>]] ;
    [FOCUSRECT <nFocusRectStyle> [COLOR <nFocusRectColor>]] ;
    [OUTLINE] ;
    [BORDERCOLOR <nBorderColor>] ;
    [RADIUS <nRadius>] ;
    [SELECTENABLE [SELECTED] [SELECTCOLOR <nFGCSelect [,<nBGCSelect>]] ;
    [WHEN <bWhen>] ;
    [HIDE <bHide>  ;
    [PARENT <oParent>] ;
    [PARENTID <cParentID>] ;
    [HELPCODE <cHelpCode>] ;
    [FONT <bocFont>] ;
    [PIXEL] ;
    [OBJECT <oObject>] ;
    [TOOLTIP <bcToolTip>] ;
    [MESSAGE <bcMsg> [INTO <oMsgBox>]] ;
    [CURSOR <naCursor>] ;
    [CARGO <xCargo>] [CARGO "CANCEL"] ;
    [PREEVAL <bPreEval>] ;
    [EVAL <bEval>] ;
    [RELATIVE <oRel>] ;
    [ID <cId>] ;
    [TITLE <cTitle>] ;
    [ACCELKEY <anAccel>] ;
    [GOTFOCUS <bGotFocus>] ;
    [LOSTFOCUS <bLostFocus>] ;
    [TABSTOP] ;
    [NOTABSTOP] ;
    [TABGROUP <nTabGroup>] ;
    [VISIBLE] ;
    [INVISIBLE] ;
    [GROUP <cGroup>] ;
    [STATIC] ;
    [RESIZE <aResize> [SCALEFONT] ] ;
    [RESTYPE <cResType>] ;
    [RESFILE <cResFile>] ;
    [SOUND <cSound>] ;
    [DRAG <bDrag> [DIALOG <bDD>] ;
    [DROP <bDrop> [CURSOR <nDropCursor>] ;
    [CONFIG <oConfig>] ;
    [SHADOW <nShadowType>]
 ;

Arguments:

<nRow> and <nCol> are the row and column of the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE argument is used.
If no parent is assigned, then the parent is the Dialog box.
IF the PIXEL option is set to .TRUE. in DCGETOPTIONS, then
the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel
mode by including PIXEL as a command argument.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

CAPTION <xCaption> is the part of the PushButton object that
is displayed within the area of the pushbutton. The caption may
be one of the following:

1) A character string.  An ampersand (&) preceding a character in
   the text assigns the ALT-<char> key as a hotkey for the
   pushbutton and underlines the character.  A tilde (~) preceding
   the character will only underline the character and will not
   enable the hot-key.  A tilde (~) could be used with the
   ACCELKEY clause to establish the hot key(s).

2) A bitmap resource. The numeric resource ID of the bitmap is
   assigned to the instance variable.  If a resource ID is used,
   it must be defined in a resource file that is linked to the
   EXE file using the resource compiler.

3) A bitmap object created with the XbpBitMap() class.

4) A code block.  A code block is evaluated whenever the
   DC_GetRefresh() function is called.  This is used to change
   the caption dynamically after the pushbutton object is created.
   The code block must return either a character string, a bitmap
   numeric resource or a bitmap object.

BITMAP <xBitMap> may be a bitmap resource, a bitmap object, or
a code block. ALIGN <nBMAlign> is a numeric value, from XBP.CH
starting with XBALIGN_* that will determine how the bitmap will be
aligned on the button. Example: XBALIGN_LEFT+XBALIGN_CENTER.
OFFSET <nBMOffset> is the amount of offset, in pixels, of the bitmap
from the edge of the button to which it is aligned.  SCALE <nBmpScale>
is the scale factor of the bitmap.  The default is 1.

CAPTIONARRAY <aCaptions> is an array of captions.  This argument is
used in lieu of the CAPTION and BITMAP clauses above.  Each subarray
in the array has the following structure:

Element  Type    Description
-------  ------  --------------------------------------------------
  [1]     C/O    Caption string or Bitmap object
  [2]     N      Foreground color
  [3]     N      Start Row, in pixels from top
  [4]     N      Start Column, in pixels from top
  [5]     N      End Row, in pixels from top (bitmap only)
  [6]     N      End Column, in pixels from top (bitmap only)
  [7]     N      Alignment. XBALIGN_* from XBP.CH.
  [8]     C      Font compound name or Font object (caption only)

TILEBITMAP <xTile> is a bitmap resource or bitmap object to use
as a tiled background for the button.

SIZE <nWidth>,<nHeight> is the width and height of the
PushButton.  If the PIXEL option is set to .TRUE. in DCGET
OPTIONS, then the numbers are in pixels otherwise they are
in standard text-based numbers.

COLOR <ncFGc>, <ncBGc> are foreground and background colors.
They may be character strings representing valid text-based
colors supported by SetColor() or they may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH. If <bncFGc> is a
code block is must return a 2-element array containing a
foreground and background color.  The COLOR clause is supported
only when using the STATIC clause.

MOUSECOLOR <ncFGCMouse>, <ncBgCMouse> are foreground and
background colors that will control the color of the button when
the mouse is moved over the button.

MOUSESOUND <abMouseSound> is a character string or code block that
returns the name of a .WAV file that will be used to play a sound
when the mouse is moved over the button.

MOUSEFONT <ocMouseFont> is a font compound name or font object
that defines the font to use for the caption text when the mouse
is moved over the button.

CLICKCOLOR <ncFGCClick>, <ncBgCClick> are foreground and
background colors that will control the color of the button when
the mouse is clicked on the button.

OUTLINE will cause the button to be outlined.
BORDERCOLOR <nBorderColor> defines the color of the outline.

DISABLEDCOLOR <nDisabledFGColor> and <nDisabledBGColor> are used
to set the Foreground (text) and Background color of the button
when the button is disabled.  GRAYBITMAP will also cause the
bitmap to be grayed out when disabled.

SELECTENABLE will enable a mode that allows a set of pushbuttons
(with the same parent) to behave like radio buttons.  This will
set the ::selected flag when the button is pushed and thereby
color the button with the <nFGCSelect> and <nBGCSelect> colors.
All other buttons with the same parent will be unselected.
SELECTED will set this button as the default selected button.

GRADIENT <nGradStep> is a positive number that determines the scale
of gradient to use, starting with the color of the background color.
REVERSE will reverse the gradient when the mouse is moved over the
button.  LEVEL <nLevel> is a value to use to change the gradient
level.  Run \exp19\samples\buttonxp\buttpicker.exe to try different
gradient levels.  STYLE <nGradStyle> is the style of the gradient
based on the below table.

Style     Description
------   ---------------------------
 1       Vertical (top to bottom)
 2       Vertical (bottom to top)
 3       Horizontal (left to right)
 4       Horizontal (right to left)
 5       Concentric (inner to outer)
 6       Concentric (outer to inner)

FOCUSRECT <nFocusRectStyle> is the style of rectangle to paint on
the button when it receives focus.  See the below table.
<nFocusRectColor> is the color of the focus rectangle.

Style     Description
------   ---------------------------

 0       None
 1       Dotted Interior
 2       Normal Outline
 3       Heavy Outline

ACTION <bAction> is a codeblock that is to be evaluated
when the pushbutton is activated.

MENUACTION <bMenuAction> is a codeblock that is to be evaluated
when the menu button (down arrow) is clicked.  This clause will
cause a menu button, separated by a vertical line, to be painted
on the right side of the pushbutton.

RADIUS <nRadius> is how much to round the corners of the rectangle.
This is a positive integers which determines the distance (radius of
curvature) from a corner to the middle of the rectangle.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.  If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

OBJECT <oObject> is the name of the memory variable to assign to
this object.

FONT <cFont> is a character string defining an optional font.
The font string must conform to the Xbase++ standard, ie.
"10.Courier Bold". It may also be a font object or a code block
that returns a character string or a font object to later
refresh with DC_GetRefresh().

MESSAGE <bcMsg> is the message you want to display in the
message area of the dialogue screen defined by the DCMESSAGEBOX
command when the object is in focus.  Optionally, INTO <oMsgBox>
will designate which message box to display the message into.
If the INTO clause is not used, then the last message box in the
GetList is the default. <oMsgBox> may also be any object that
supports the :setCaption() method.If <bcMsg> is a code-block,
it must return a character string.

HELPCODE <cHelp> is a character string that is passed to the
DC_HelpF1() function if F1 is pressed or the HELP button
is clicked when this object has focus.  This HELPCODE allows
the Help system to override the passing of the Procedure and
Varname for more specific context-help.

TOOLTIP <bcToolTip> is a character string which will display
as a "Tool Tip" next to the object when the cursor is passed
over the object. A semi-colon within the text indicates a new
line.  If <bcToolTip> is a code-block, it must return a character
string.  NOTE: The Tooltip painting method is run in another
thread, therefore the codeblock should not run code that points
to the current work area.  It may however, contain local, public
or private variables.

CURSOR <naCursor> may be either a numeric value or an array of
3 elements which defines an optional mouse pointer to use for
this object.  System mouse pointers start with
XBPWINDOW_POINTERTYPE_ and are defined in XPB.CH.  The default
pointer is XBPWINDOW_POINTERTYPE_POINTER.  <naCursor> may be a
numeric resource ID that points to a Bit-Map that has been
compiled with the resource compiler and linked to the .EXE.
<naCursor> may be a 3-element array described as follows:

  Element  Type  Description
  -------  ---- ---------------------------------------------
    [1]      C   Optional name of .DLL containing the pointer
                 resource.

    [2]      N   The numeric resource ID of the pointer.  If
                 element 1 is a NIL, then this resource must be
                 linked into the .EXE.

    [3]      N   The type of resource as defined in XBP.CH.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

Use the clause CARGO 'CANCEL' if the pushbutton is to be used
to exit a dialog without testing validations.  This will insure
that if the pushbutton is clicked while in a DCGET with a
validation the validation code block will not be evaluated.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the object will be disabled and grayed.
If the value returned is .TRUE. then the object will be enabled.
The object is passed as a parameter to the code block.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.
The object is passed as a parameter to the code block.

ACCELKEY <anAccel> is a numeric "hot-key" assignment that will set
focus to the pushbutton object and activate its associated code block
when the hot-key is pressed.  The key must be a valid key with
the prefix xbeK_*.  These keys are defined in APPEVENT.CH.
<anAccel> may also be an array of numeric values to assign more
than one key to the object.

GOTFOCUS <bGotFocus> is a code block that is evaluated when this
object receives input focus.  <bGotFocus> := {|uNIL1,uNIL2,self|...}

LOSTFOCUS <bLostFocus> is a code block that is evaluated when this
object loses input focus.  <bLostFocus> := {|uNIL1,uNIL2,self|...}

TABSTOP will cause the object (Xbase Part) to be set when using
the Tab key.  Note: When logical groups are defined in a dialog
using TABGROUP <nTabGroup>, TABSTOP is usually set to .T. (true)
for the first dialog element in the group.  This allows the first
dialog element of a group to be activated using the Tab key.

NOTABSTOP will cause the object (Xbase Part) to be ignored when
using the Tab key. This clause is needed only to override any
default setting of TabStop by the DCGETOPTIONS [TABSTOP] command.

TABGROUP <nTabGroup> allows objects (Xbase Parts) that are created
immediately after one another in the GetList to be combined into
logical groups. This allows the user to navigate within a dialog
from group to group by pressing the Tab key.  Within a group of
dialog elements navigation is performed using the cursor keys.

Only constants defined in the XBP.CH file can be used as values
for this instance variable.  The following table lists the
available constants:

#define constants for <nTabGroup>:

 Constant             Description

 XBP_NO_GROUP     *)  Dialog element does not belong to a group
 XBP_BEGIN_GROUP      Dialog element is the first in a group
                      (this begins the definition of the group)
 XBP_WITHIN_GROUP     Dialog element is within a group
 XBP_END_GROUP        Dialog element is the last in a group
                      (this ends the definition of the group)

*) Default value

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS.

FOCUSCOLOR * is used to determine the color of any text on the
button when it receives focus by passing the mouse over the button.
<anTextColor> is the color of the text.  If this argument is a
NIL the text color will not be changed.  <anFrameColor> is the
color of a frame that is drawn around the perimeter of the button
to hilight the button when it receives focus.  If this argument
is a NIL, there will be no frame drawn.  These arguments may be
be a numeric color defined by GRA_CLR_* in GRA.CH or a 3 element
array of RGB colors.

RESIZE <aResize> is an optional array of two (2) elements
used for resizing and repositioning the object when the parent
is resized.

NOTE: RESIZE is to be used in conjunction with the RESIZE clause
      of DCGETOPTIONS. See the RESIZE clause of DCGETOPTIONS for
      examples.

      The optional SCALEFONT clause will automatically scale the
      font size up or down when the object is resized.

RESTYPE <cResType> provides support for bitmap resources of type
BMP, PNG, GIF and JPEG that have been linked into a .RES file to
be used as the caption.

Example:

@ .. DCPUSHBUTTONXP CAPTION 2000 RESTYPE GIF

// myres.arc
USERDEF GIF
2000 = FILE ".\GIFChart.GIF"

RESFILE <cResFile> is the name of the .DLL that contains the
resource stated in the RESTYPE <cResType> clause.  If this parameter
is not used, then the resource must be in the .EXE.

SOUND <cSound> is the name of a .WAV file to play when the button
is clicked.

SCALEBITMAP will shrink or enlarge a bitmap caption to fit
exactly within the button size.  Note: bitmaps should be 24-bit
(hi-color) for this to work correctly.

DRAG <bDrag> is a codeblock to evaluate when the left mouse button
is clicked in the object and the drag is started.  The return
value of the code block will be stored in memory to be later
retrieved by the Drop operation. A pointer to the clicked on
object is passed to the code block.

DIALOG <bDD> is a codeblock that will evaluate when the drag is
started.  This is used to call a function that will create a
dialog window which will move with the mouse during the drag.
The dialog window will be destroyed upon the drop operation
or the release of the mouse.

Ex: DRAG {|o|o:getData()} DIALOG {|mp1,mp2,oXbp|DragDialog(mp1,mp2,oXbp)} ;

DROP <bDrop> is a codeblock to evaluate when the left mouse button
is released in the object and the drag is ended.  A pointer to
the object and the value stored in memory at the start of the
Drag are passed to the code block.

CURSOR <nDropCursor> is the mouse cursor that will show when it
is moved over this object during a drag operation.

Ex: DROP {|o,x|o:setData(x),o:invalidateRect()} ;
       CURSOR CURSOR POINTER_DATADROP_ASSIGN

CONFIG <oConfig> is a configuration object that was previously
created with the DC_XbpPushButtonXPConfig():new() method.
Configuration parameters are defaulted to the values included
in the <oConfig> iVars.

SHADOW <nShadowType> is a value from 0 to 9.  0 indicates no
shadow. 1 thru 9 indicates a shadow of various styles.
Run \exp19\samples\buttonxp\buttpicker to try different styles.

Notes:

This command or class is only available in Xbase++ 1.9 (build 331 or later) because it uses the ownerdraw capability of the XbpPushButton() class.

Use the clause CARGO 'CANCEL' if the pushbutton is to be used to exit a dialog without testing validations. This will insure that if the pushbutton is clicked while in a DCGET with a validation the validation code block will not be evaluated.

For an example of DCPUSHBUTTONXP buttons, see the sample program in \exp19\samples\buttonxp.

The function DC_BitmapTransparentColor() may be used to set the default transparent color for pushbuttons that have bitmaps as captions.

DCPUSHBUTTONXP objects are created from the DC_XbpPushButtonXP() class which is derived from the XbpPushButton() class.

Designing DCPUSHBUTTONXP objects to look exactly the way you would want can be a time-consuming task, therefore it is recommended that you use a special utility program for this purpose. See \exp19\samples\buttonxp\buttpicker.exe.

Files:

DCDIALOG.CH

See Also:

   @ DCTOOLBAR
   @ DCPUSHBUTTON
   DCADDBUTTONXP
   DC_XbpPushButtonXPConfig()


@ DCQUICKBROWSE

Create a QUICKBROWSE object for displaying with GUI reader

The command @..DCQUICKBROWSE creates a new QuickBrowse object and adds the object to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD GUI command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> @..DCQUICKBROWSE objects can be combined with any objects that that use the DCDIALOG system, such as DCBROWSECOL, @..DCSAY..GET, @..DCRADIO, @..DCPUSHBUTTON or @..DCMULTILINE.

Syntax:

 @ <nRow>, <nCol> DCQUICKBROWSE <oBrowse> ;
    [ALIAS <cAlias>] ;
    [FIELDS <aFields>] ;
    [DATA <xData>] ;
    [COLUMNS <aColumns>] ;
    [COLTYPE <aColType>] ;
    [COLREPRESENTATION <aColRep>] ;
    [COLWIDTH <aColWidth>] ;
    [COLALIGN <aColAlign>] ;
    [HEADERS <aHeaders>] ;
    [SIZE <nWidth> [,<nHeight>]] ;
    [STYLE <nStyle>] ;
    [PARENT <oParent>] ;
    [PARENTID <cParentId>] ;
    [INTO <uVar>] ;
    [POINTER <nVar>] ;
    [ITEMMARKED <bItemMarked>] ;
    [DATALINK, ITEMSELECTED <bItemSelected>] ;
    [EDIT <nEditEvent> ;
       [ MODE <nEditMode>] ;
       [ ACTION <bEditAction>] ;
       [ EXIT <bEditExit> ] ] ;
    [INSERT <nInsertEvent> ;
       [ DEFAULT <abDefault>] ;
       [ ACTION <bInsertAction>] ;
       [ EXIT <bInserExit>] ] ;
       [ APPEND <nAppendEvent>] ;
    [DELETE <nDeleteEvent> ;
       [ ACTION <bDeleteAction>] ;
       [ EXIT <bDeleteExit> ] ] ;
    [HANDLER <handler> [REFERENCE <xRef>]] ;
    [PRESENTATION <aPres>] ;
    [MESSAGE <cMsg> [INTO <oMsg>]] ;
    [COLOR <bncFgC> [,<ncBgC>]] ;
    [WHEN <bWhen>] ;
    [HIDE <bHide>] ;
    [FONT <bocFont>] ;
    [CARGO <xCargo>] ;
    [CURSORMODE <nCursorMode>] ;
    [PIXEL] ;
    [PREEVAL <bPreEval>] ;
    [EVAL <bEval>] ;
    [RELATIVE <oRel>] ;
    [TITLE <cTitle>] ;
    [ID <cId>] ;
    [ACCELKEY <anAccel>] ;
    [GOTFOCUS <bGotFocus>] ;
    [LOSTFOCUS <bLostFocus>] ;
    [TABSTOP] ;
    [NOTABSTOP] ;
    [NOVSCROLL] ;
    [NOHSCROLL] ;
    [TABGROUP <nTabGroup>] ;
    [VISIBLE] ;
    [INVISIBLE] ;
    [GROUP <cGroup>] ;
    [RESIZE <aResize>] ;
    [DRAG <bDrag> [DIALOG <bDD>] ;
    [DROP <bDrop> [CURSOR <nDropCursor>] ;
    [SUBCLASS <cSubClass>]

Arguments:

<nRow>, <nCol> are the coordinates on the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE <oRel> argument is
used.  If no parent is assigned, then the parent is the Dialog
box.  IF the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel mode by
including PIXEL as a command argument.

<oBrowse> is the name of the variable to assign as a storage
place for this object.

SIZE <nWidth>,<nHeight> is the width and height of the
prompt.  If the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based numbers.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

ALIAS <cAlias> defines the browse as a database browse. <cAlias)
is a variable containing the alias of the database to browse.

 or

DATA <aData> defines the browse as an array browse.  <aData> is
a variable containing a pointer to the array to browse.  ELEMENT
<nElement> is an optional clause defining the selected element of
<aData>.

COLUMNS <aColumns> is a one-dimensional array of column indexes.
for the columns of <aData> when browsing an array.  NOTE: this
parameter is needed when creating a browse where columns are
defined by this clause rather than defined later with the
DCBROWSECOL command.

FIELDS <aFields> is a one-dimensional array of field names for
the fields to be accessed. If not specified, the DacPagedDataStore
object caches all fields of the specified work area.  NOTE: this
parameter is needed when creating a browse where fields are
defined by this clause rather than defined later with the
DCBROWSECOL command.

HEADERS <aHeaders> is a one-dimensional array of column headings.
NOTE: this parameter is needed when creating a browse where
headers are defined by this clause rather than defined later
with the DCBROWSECOL command.

STYLE <nStyle> is used to choose a pre-defined display style.
The below constants are defined in XBP.CH.

Style definitions

  Constant         Description

  XBP_STYLE_PLAIN  Plain appearance
  XBP_STYLE_FANCY  Fancy style
  XBP_STYLE_3D     3D style

COLTYPE <aColType> is an array defining the type of each column.
Each element is an optional sub-array of three elements:
{ <cValtype>, <nDisplayType>, <cPicture> }.   NOTE: this
parameter is needed when creating a browse where column types
are defined by this clause rather than defined later with the
DCBROWSECOL command.

<cValType> is the type of data displayed in the column. It is
specified using a letter equivalent to the return value of the
Valtype() function. These are usually the characters "C", "D",
"L" or "N".

<nDisplayType> defines the display type of the column, or how
data is visualized. Data can be represented in textual (default)
or graphic form. Constants defined in XBP.CH are used for
<nDisplayType> . They are listed in the table below:

Constants used for <nDisplayType>

 Constant                  Description

 XBPCOL_TYPE_BITMAP        The column displays bitmaps
 XBPCOL_TYPE_ICON          The column displays icons
 XBPCOL_TYPE_SYSICON       The column displays system-icons
 XBPCOL_TYPE_FILEICON      The column displays normal file-icons
 XBPCOL_TYPE_FILEMINIICON  The column displays small file-icons
 XBPCOL_TYPE_TEXT      *)  The column displays textual data

 *) default value

<cPicture> optionally defines a picture string for textual data.
Refer to the Transform() function for picture formatting rules.

COLREPRESENTATION <aColRep> is an array of information about the
presentation of columns.  There is one sub-array for each column
defined as follows: <aResource>

<aResource> := { <xValue>, <nNormalID>, <nHiliteID> }

  When data in a column cell has the value <xValue>  the image
  with the resource ID <nNormalID> is displayed in the cell. If
  the cell is to be hilited, the image with the ID <nHiliteID> is
  displayed. The value -1 is valid for both resource IDs. In this
  case, nothing is displayed in the cell. Once a visual
  representation is defined, it can be voided by specifying NIL
  for the resource IDs.

COLWIDTH <aColWidth> is a one-dimensional array of numeric column
widths in pixels.

COLALIGN <aColAlign> is a one-dimensional array of numeric values
to define horizontal and vertical alignment:

 Constants for alignment

 Constant          Description

 XBPALIGN_TOP      Alignment at the top
 XBPALIGN_LEFT     Alignment on the left
 XBPALIGN_BOTTOM   Alignment at the bottom
 XBPALIGN_RIGHT    Alignment on the right
 XBPALIGN_HCENTER  Horizontally centered
 XBPALIGN_VCENTER  Vertically centered

INTO <nVar> is a memory variable to store a pointer to the record
number of the selected row.  Each time the user clicks on a new
row of a database browse, the record number will be stored in
<nVar>.

ITEMMARKED <bItemMarked> is a code block to evaluate every
time the user clicks to a new row of the browse.  The browse
object is passed to the code block.

POINTER <nVar> is a memory variable to store the current array
element pointer. This clause  is used only when browsing arrays.
Each time the user clicks on a new row of the array browse, the
browse row (element number) will be stored in <nVar>.  <nVar>
must be initialized to a numeric value.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.  If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

ITEMSELECTED, DATALINK <bItemSelected> is an optional code block
to evaluate whenever the user double-clicks the mouse or presses
the ENTER key within the browse area.  The browse object is passed
as a parameter to the code block.

EDIT <nEditEvent> is an optional clause that enables "cell-editing"
of the browse cells whenever a specified event occurs that is
associated with the browse object.  NOTE: Cell-Editing will work
only if all browse columns are created via the DCBROWSECOL
command.  <nEditEvent> is a numeric value equivalent to an xbe*
event or keyboard value which has been defined in APPEVENT.CH.
For example, cell editing will occur within the selected cell
when <nEditEvent> is equal to xbeBRW_ItemSelected and the cell
is selected with a mouse double-click or the ENTER key is
pressed.  MODE <nEditMode> is the navigation mode within the
cells.  <nEditMode> is a numeric value from the following table:

 <nEditMode>                 Description
 -----------                 ------------------------------------
 DCGUI_BROWSE_EDITEXIT       Exit cell editing after ENTER key
 DCGUI_BROWSE_EDITACROSS     Move to next column after ENTER key
 DCGUI_BROWSE_EDITDOWN       Move to next row after ENTER key
 DCGUI_BROWSE_EDITACROSSDOWN Move to next column after ENTER key
                             and move to next row at end of column

<bEditAction> is an optional code block that is evaluated before
the cells are edited.  <bEditExit> is an optional code block that
is evaluated after the cells are edited.  The browse object is
passed as a parameter to <bEditAction> and <bEditExit>.

INSERT <nInsertEvent> is an optional clause that enables the
inserting of an element into the array and editing the cell
items. <nInsertEvent> is a numeric value equivalent to an xbe*
event or keyboard value which has been defined in APPEVENT.CH.
For example, cell insertion will occur at the selected row of
the browse when <nEditEvent> is equal to xbeK_INS and the browse
is in focus and the INSERT key is pressed.  <bInsertAction> is an
optional code block that is evaluated before a new element is
inserted in the array.  <bInsertExit> is an optional code block
that is evaluated after exiting the cell editor.  The Browse
Object is passed as a parameter when evaluating <bInsertAction>
and <bInsertExit>.  APPEND <nAppendEvent> is an additional optional
clause that can only be used with the INSERT clause.  <nAppendEvent>
is a numeric value equivalent to an xbe* event or keyboard value.
This event forces the insertion of the new element at the end of
the array rather than at the selected row.

DELETE <nDeleteEvent> is an optional clause that enables the
deleting the current selected element (row) of an array or the
currently selected record. <nDeleteEvent> is a numeric value
equivalent to an xbe* event or keyboard value which has been
defined in APPEVENT.CH.  For example, cell deletion will occur
at the selected row of the browse when <nEditEvent> is equal to
xbeK_DEL and the browse is in focus and the DELETE key is pressed.
<bDeleteAction> is an optional code-block that is evaluated before
the element is deleted.  <bDeleteExit> is an optional code block
that is evaluated after the element is deleted.  The Browse Object
is passed as a parameter when evaluating <bDeleteAction> and
<bDeleteExit>.

HANDLER <cEventHandler> is the name of a Function which points
to a custom event handler when cell editing.  The cell editor
uses it's own, default event handler to manage the objects
during cell editing.  The default event handler makes a call
to the custom event handler before processing it's default
events. The custom event handler uses Appevent() to get
information on the current event and passes the following
parameters:

 1. nEvent   - The event type.
 2. mp1      - The first event parameter.
 3. mp2      - The second event parameter.
 4. oXbp     - A pointer to the object creating the event.
 5. oDlg     - A pointer to the main dialogue object.
 6. aGetlist - A pointer to the GetList array.
 7. aRef     - A pointer to an optional Reference array.

 The Function should look like this:

 STATIC FUNCTION MyHandler ( nEvent, mp1, mp2, oXbp, oDlg,
                             aGetlist, aRef )

 /* custom code */

 RETURN DCGUI_NONE

The function must return a numeric value which controls the
behavior of the event loop as follows:

 Return Value   Behavior
 ------------   --------------------------------------------
 DCGUI_NONE     Continue processing the event
 DCGUI_IGNORE   Ignore event
 DCGUI_CLEAR    Ignore event and clear all events from queue
 DCGUI_EXIT     Exit the Cell editor

REFERENCE <aRef> is any array to pass to the custom event handler.
Programming dialogue systems that must manipulate many variables
is much simpler if all the variables are placed into a single
array and then passed to the dialogue system and its event
handler.

INTO <uVar> is the name of a numeric variable to store the current
record pointer.

FONT <cFont> is a character string defining an optional font.
The font string must conform to the Xbase++ standard, ie.
"10.Courier Bold". It may also be a font object or a code block
that returns a character string or a font object to later
refresh with DC_GetRefresh().

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the Browse object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.

CURSORMODE <nCursorMode> determines the browse cursor to be
displayed by the Browse object. #define constants from XBP.CH
must be used for this mode:

 Constant            Description

 XBPBRW_CURSOR_NONE  No visible cursor
 XBPBRW_CURSOR_CELL  Cell cursor (default)
 XBPBRW_CURSOR_ROW   Row cursor

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

COLOR <bncFGc>, <ncBGc> are foreground and background colors.
They may be character strings representing valid text-based
colors supported by SetColor() or they may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH. IF <bncFGc> is a
code block is must return a 2-element array containing a
foreground and background color.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

MESSAGE <bcMsg> is the message you want to display in the
message area of the dialogue screen defined by the DCMESSAGEBOX
command when the object is in focus.  Optionally, INTO <oMsgBox>
will designate which message box to display the message into.
If the INTO clause is not used, then the last message box in the
GetList is the default.  If <bcMsg> is a code-block, it must
return a character string.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the object will be disabled and grayed.
If the value returned is .TRUE. then the object will be enabled.

ACCELKEY <anAccel> is a numeric "hot-key" assignment that will set
focus to the checkbox object when the hot-key is pressed.  The key
must be a valid key with the prefix xbeK_*.  These keys are
defined in APPEVENT.CH.  <anAccel> may also be an array of numeric
values to assign more than one key to the object.

GOTFOCUS <bGotFocus> is a code block that is evaluated when this
object receives input focus.  <bGotFocus> := {|uNIL1,uNIL2,self|...}

LOSTFOCUS <bLostFocus> is a code block that is evaluated when this
object loses input focus. <bLostFocus> := {|uNIL1,uNIL2,self|...}

TABSTOP will cause the object (Xbase Part) to be set when using
the Tab key.  Note: When logical groups are defined in a dialog
using TABGROUP <nTabGroup>, TABSTOP is usually set to .T. (true)
for the first dialog element in the group.  This allows the first
dialog element of a group to be activated using the Tab key.

NOTABSTOP will cause the object (Xbase Part) to be ignored when
using the Tab key. This clause is needed only to override any
default setting of TabStop by the DCGETOPTIONS [TABSTOP] command.

NOVSCROLL will suppress the vertical scroll bar.

NOHSCROLL will suppress the horizontal scroll bar.

TABGROUP <nTabGroup> allows objects (Xbase Parts) that are created
immediately after one another in the GetList to be combined into
logical groups. This allows the user to navigate within a dialog
from group to group by pressing the Tab key.  Within a group of
dialog elements navigation is performed using the cursor keys.

Only constants defined in the XBP.CH file can be used as values
for this instance variable.  The following table lists the
available constants:

#define constants for <nTabGroup>:

 Constant             Description

 XBP_NO_GROUP     *)  Dialog element does not belong to a group
 XBP_BEGIN_GROUP      Dialog element is the first in a group
                      (this begins the definition of the group)
 XBP_WITHIN_GROUP     Dialog element is within a group
 XBP_END_GROUP        Dialog element is the last in a group
                      (this ends the definition of the group)

*) Default value

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

RESIZE <aResize> is an optional array of two (2) elements
used for resizing and repositioning the object when the parent
is resized.

NOTE: RESIZE is to be used in conjunction with the RESIZE clause
      of DCGETOPTIONS. See the RESIZE clause of DCGETOPTIONS for
      examples.

DRAG <bDrag> is a codeblock to evaluate when the left mouse button
is clicked in the object and the drag is started.  The return
value of the code block will be stored in memory to be later
retrieved by the Drop operation. A pointer to the clicked on
object is passed to the code block.

DIALOG <bDD> is a codeblock that will evaluate when the drag is
started.  This is used to call a function that will create a
dialog window which will move with the mouse during the drag.
The dialog window will be destroyed upon the drop operation
or the release of the mouse.

Ex: DRAG {|o|o:getData()} DIALOG {|mp1,mp2,oXbp|DragDialog(mp1,mp2,oXbp)} ;

DROP <bDrop> is a codeblock to evaluate when the left mouse button
is released in the object and the drag is ended.  A pointer to
the object and the value stored in memory at the start of the
Drag are passed to the code block.

CURSOR <nDropCursor> is the mouse cursor that will show when it
is moved over this object during a drag operation.

Ex: DROP {|o,x|o:setData(x),o:invalidateRect()} ;
       CURSOR CURSOR POINTER_DATADROP_ASSIGN

SUBCLASS <cSubClass> is a string containing a class name that
will be used to create the class, rather than DC_XbpQuickBrowse().
This class should inherit from DC_XbpQuickBrowse().
See the example in \exp19\samples\subclass.

Notes:

The browse object created by @ DCQUICKBROWSE is an object of the XbpQuickBrowse() class, therefore it can be manipulated with any iVar or method supported by XbpQuickBrowse().

Examples:

* Example 1 - Browsing a Database

FUNCTION XTest_1()

LOCAL GetList := {}, oBrowse, aFields, aHeaders, aPres

SET DEFA TO ..\XDOC
USE EXPRESS VIA FOXCDX EXCLUSIVE ALIAS 'XDOC'
SET INDEX TO EXPRESS.CDX
OrdSetFocus('COMMAND')
SET DEFA TO

aFields := { 'XDOC->COMMAND', ;
             'XDOC->SHORT', ;
             'XDOC->TYPE', ;
             'XDOC->MODULE', ;
             'XDOC->SEE_ALSO'}

aHeaders := { 'Command','Short Description','Type','Module','See Also'}

@ 1,1 DCQUICKBROWSE ALIAS 'XDOC' SIZE 70,20 ;
   OBJECT oBrowse ;
   FIELDS aFields HEADERS aHeaders ;
   STYLE XBP_STYLE_FANCY ;
   CURSORMODE XBPBRW_CURSOR_CELL

DCREAD GUI FIT ADDBUTTONS ;
   TITLE 'Quick-Browsing a Database'

RETURN nil

* Example 2 - browsing an array (method 1)

FUNCTION XTest_2()

LOCAL GetList := {}, oBrowse, aDirectory := Directory(), aHeaders, ;
      aColumns, aColType, aColAlign, aColWidth

aColumns :=     { ;
      F_NAME          , ; // Display files as icons
      F_NAME          , ; // Display file names as text
      F_SIZE          , ;
      F_WRITE_DATE    , ;
      F_WRITE_TIME    , ;
      F_CREATION_DATE , ;
      F_CREATION_TIME   }

aHeaders :=     { ;
      " "             , ;
      "File name    " , ;
      "    File size" , ;
      "  Access date" , ;
      "  Access time" , ;
      "Creation date" , ;
      "Creation time"   }

aColType :=     { ;
      { 1, XBPCOL_TYPE_FILEMINIICON }, ;
      nil, ;
      nil, ;
      nil, ;
      nil, ;
      nil, ;
      nil  }

aColWidth :=    { ;
      32, ;
      nil, ;
      nil, ;
      nil, ;
      nil, ;
      nil, ;
      nil }

aColAlign :=    { ;
   XBPALIGN_VCENTER + XBPALIGN_HCENTER, ;
   XBPALIGN_RIGHT + XBPALIGN_VCENTER, ;
   XBPALIGN_RIGHT + XBPALIGN_VCENTER, ;
   XBPALIGN_RIGHT + XBPALIGN_VCENTER, ;
   XBPALIGN_RIGHT + XBPALIGN_VCENTER, ;
   XBPALIGN_RIGHT + XBPALIGN_VCENTER, ;
   XBPALIGN_RIGHT + XBPALIGN_VCENTER  }

@ 1,1 DCQUICKBROWSE DATA aDirectory SIZE 60,20 ;
   OBJECT oBrowse ;
   COLUMNS aColumns ;
   HEADERS aHeaders ;
   COLTYPE aColType ;
   COLWIDTH aColWidth ;
   COLALIGN aColAlign

DCREAD GUI FIT ADDBUTTONS ;
   TITLE 'Quick-Browsing an Array'

RETURN nil

* Example 2 - browsing an array (method 2)

FUNCTION XTest_3()

LOCAL GetList := {}, oBrowse, aDirectory := Directory(), aHeaders, ;
      aColumns, aColType, aColAlign, aColWidth

aColumns :=     { ;
      F_NAME          , ; // Display files as icons
      F_NAME          , ; // Display file names as text
      F_SIZE          , ;
      F_WRITE_DATE    , ;
      F_WRITE_TIME    , ;
      F_CREATION_DATE , ;
      F_CREATION_TIME   }

aHeaders :=     { ;
      " "             , ;
      "File name    " , ;
      "    File size" , ;
      "  Access date" , ;
      "  Access time" , ;
      "Creation date" , ;
      "Creation time"   }

aColType :=     { ;
      { 1, XBPCOL_TYPE_FILEMINIICON }, ;
      nil, ;
      nil, ;
      nil, ;
      nil, ;
      nil, ;
      nil  }

aColWidth :=    { ;
      32, ;
      nil, ;
      nil, ;
      nil, ;
      nil, ;
      nil, ;
      nil }

aColAlign :=    { ;
   XBPALIGN_VCENTER + XBPALIGN_HCENTER, ;
   XBPALIGN_RIGHT + XBPALIGN_VCENTER, ;
   XBPALIGN_RIGHT + XBPALIGN_VCENTER, ;
   XBPALIGN_RIGHT + XBPALIGN_VCENTER, ;
   XBPALIGN_RIGHT + XBPALIGN_VCENTER, ;
   XBPALIGN_RIGHT + XBPALIGN_VCENTER, ;
   XBPALIGN_RIGHT + XBPALIGN_VCENTER  }

@ 1,1 DCQUICKBROWSE DATA aDirectory SIZE 60,20 ;
   OBJECT oBrowse

FOR i := 1 TO 7
  DCBROWSECOL PARENT oBrowse ;
     ELEMENT aColumns[i] ;
     HEADER aHeader[i] ;
     WIDTH aColWidth[i] ;
     TYPE aColType[i] ;
     ALIGN aColAlign[i]
NEXT

DCREAD GUI FIT ADDBUTTONS ;
   TITLE 'Quick-Browsing an Array'

RETURN nil

Files:

DCDIALOG.CH

See Also:

   @ DCBROWSE
   DCBROWSECOL


@ DCRADIOBUTTON

Create a RADIO BUTTON object for displaying with GUI reader

The command @..DCRADIOBUTTON creates a new Radio Button definition and adds it to the array named GETLIST which is later processed by the DC_Read*() functions or by the DCREAD * commands. The GETLIST array must be first declared and initialized to the value of {}. <br><br> The command DCREAD GUI creates the DC_Xbp*() objects and activates the edit mode for all definitions found in the GetList array.<br><br> The command DCREAD HTML creates the DC_Html*() objects and writes the HTML source code.<br><br> A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> @..DCRADIOBUTTON objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCCHECKBOX, @..DCPUSHBUTTON or @..DCTABPAGE.<br><br>

Syntax:

@ <nRow>,<nCol> DCRADIO <uVar> ;
    [VALUE <xVal>] ;
    [ACTION <bAction>] ;
    [PARENT <oParent>] ;
    [PARENTID <cParentId>] ;
    [RADIOGROUP <aRadioGroup>] ;
    [PROMPT <bcPrompt>] ;
    [DELIMVAR <cDelim>] ;
    [OBJECT <oObject>] ;
    [COLOR <bncFgC> [,<ncBgC>] ] ;
    [FONT <bocFont>] ;
    [CARGO <xCargo>] ;
    [WHEN <bWhen>] ;
    [HIDE <bHide>] ;
    [EDITPROTECT <bProtect>] ;
    [SIZE <nWidth> [,<nHeight>]] ;
    [PRESENTATION <aPres>] ;
    [PIXEL] ;
    [TOOLTIP <bcToolTip>] ;
    [MESSAGE <bcMsg> [INTO <oMsgBox>]] ;
    [CURSOR <naCursor>] ;
    [PREEVAL <bPreEval>] ;
    [EVAL <bEval,...>] ;
    [RELATIVE <oRel>] ;
    [ID <cId>] ;
    [TITLE <cTitle>] ;
    [ACCELKEY <anAccel>] ;
    [GOTFOCUS <bGotFocus>] ;
    [LOSTFOCUS <bLostFocus>] ;
    [TABSTOP]  ;
    [NOTABSTOP];
    [TABGROUP <nTabGroup>] ;
    [VISIBLE] ;
    [INVISIBLE] ;
    [GROUP <cGroup>] ;
    [NAME <cVarName>] ;
    [RESIZE <aResize> [SCALEFONT] ] ;
    [OPTIONS <nOptions>] ;
    [DRAG <bDrag> [DIALOG <bDD>] ;
    [DROP <bDrop> [CURSOR <nDropCursor>] ;
    [SUBCLASS <cSubClass>]

Returns:

Arguments:
GUI applications:

<nRow> and <nCol> are the row and column of the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE argument is used.
If no parent is assigned, then the parent is the Dialog box.
IF the PIXEL option is set to .TRUE. in DCGETOPTIONS, then
the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel
mode by including PIXEL as a command argument.

HTML applications:

<nRow> and <nCol> are the row number and column number of
the table if the parent of this object is a DCTABLE. The
text will be inserted in the cell of the table defined by
the row/column.

<uVar> is the variable to GET.  This may be a variable
of any type except an object or array. It must not be a macro.
The <uVar> is automatically anchored via a Get-Set codeblock
created by DC_GetAnchorCB() unless <uVar> is a custom Get-Set
code block.  Macros may be used in a custom Get-Set code block.

VALUE <xValue> is the value to store into the <uVar>
variable when this object is selected.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

DELIMVAR <cDelim> is for text-based screens only and is
ignored when DC_GUI() is .TRUE.  This is a three character
sequence to use for the radio button - the default is (*).

PROMPT <bcPrompt> is the prompt to display immediately to
the right of the radio button.  It may be a character string or
a code block that returns a character string.

RADIOGROUP <aRadioGroup> is an optional array that must be
initialized as an empty array.  This option eliminates the need
to have unique parents for each radio group.  See the sample in
.\samples\radiogroup.

ACTION <bAction> is a code block to evaluate when the
radio button is selected.

SIZE <nWidth>,<nHeight> is the size of the prompt string.
NOTE: If a <nWidth> parameter is not used then the prompt will
be automatically sized to fit the string.  Use of the
:setCaption() method may produce undesirable results if the
caption width is not a sufficient length.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the object will be disabled and grayed.
If the value returned is .TRUE. then the object will be enabled.
The object is passed as a parameter to the code block.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.
The object is passed as a parameter to the code block.

EDITPROTECT <bProtect> is an optional condition tested during the
execution of the GUI gets by the DCREAD GUI command, before the
object receives input focus (before it is activated). When the
condition returns the value .T. (true), the object receives the
input focus.  Otherwise, it is skipped. <bProtect> is a code
block that must return a logical value when evaluated. The code
block is evaluated prior to the object receiving input focus.
This clause behaves similar to the WHEN clause with the exception
that the object is not disabled (grayed out).  The object is
passed as a parameter to the code block.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.  If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

OBJECT <oObject> is the name of a memory variable to store this
object after is is created.

FONT <cFont> is a character string defining an optional font.
The font string must conform to the Xbase++ standard, ie.
"10.Courier.Bold". It may also be a font object or a code block
that returns a character string or a font object to later
refresh with DC_GetRefresh().

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the Radio object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.

TOOLTIP <bcToolTip> is a character string which will display
as a "Tool Tip" next to the object when the cursor is passed
over the object. A semi-colon within the text indicates a new
line.  If <bcToolTip> is a code-block, it must return a character
string.  NOTE: The Tooltip painting method is run in another
thread, therefore the codeblock should not run code that points
to the current work area.  It may however, contain local, public
or private variables.

MESSAGE <bcMsg> is the message you want to display in the
message area of the dialogue screen defined by the DCMESSAGEBOX
command when the object is in focus.  Optionally, INTO <oMsgBox>
will designate which message box to display the message into.
If the INTO clause is not used, then the last message box in the
GetList is the default. <oMsgBox> may also be any object that
supports the :setCaption() method.If <bcMsg> is a code-block,
it must return a character string.

CURSOR <naCursor> may be either a numeric value or an array of
3 elements which defines an optional mouse pointer to use for
this object.  System mouse pointers start with
XBPWINDOW_POINTERTYPE_ and are defined in XPB.CH.  The default
pointer is XBPWINDOW_POINTERTYPE_POINTER.  <naCursor> may be a
numeric resource ID that points to a Bit-Map that has been
compiled with the resource compiler and linked to the .EXE.
<naCursor> may be a 3-element array described as follows:

  Element  Type  Description
  -------  ---- ---------------------------------------------
    [1]      C   Optional name of .DLL containing the pointer
                 resource.

    [2]      N   The numeric resource ID of the pointer.  If
                 element 1 is a NIL, then this resource must be
                 linked into the .EXE.

    [3]      N   The type of resource as defined in XBP.CH.

COLOR <ncFGc>, <ncBGc> are foreground and background colors.
They may be character strings representing valid text-based
colors supported by SetColor() or they may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH. If <bncFGc> is a
code block is must return a 2-element array containing a
foreground and background color.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

ACCELKEY <anAccel> is a numeric "hot-key" assignment that will set
focus to the checkbox object when the hot-key is pressed.  The key
must be a valid key with the prefix xbeK_*.  These keys are
defined in APPEVENT.CH.  <anAccel> may also be an array of numeric
values to assign more than one key to the object.

GOTFOCUS <bGotFocus> is a code block that is evaluated when this
object receives input focus.  <bGotFocus> := {|uNIL1,uNIL2,self|...}

LOSTFOCUS <bLostFocus> is a code block that is evaluated when this
object loses input focus.  <bLostFocus> := {|uNIL1,uNIL2,self|...}

TABSTOP will cause the object (Xbase Part) to be set when using
the Tab key.  Note: When logical groups are defined in a dialog
using TABGROUP <nTabGroup>, TABSTOP is usually set to .T. (true)
for the first dialog element in the group.  This allows the first
dialog element of a group to be activated using the Tab key.

NOTABSTOP will cause the object (Xbase Part) to be ignored when
using the Tab key. This clause is needed only to override any
default setting of TabStop by the DCGETOPTIONS [TABSTOP] command.

TABGROUP <nTabGroup> allows objects (Xbase Parts) that are created
immediately after one another in the GetList to be combined into
logical groups. This allows the user to navigate within a dialog
from group to group by pressing the Tab key.  Within a group of
dialog elements navigation is performed using the cursor keys.

Only constants defined in the XBP.CH file can be used as values
for this instance variable.  The following table lists the
available constants:

#define constants for <nTabGroup>:

 Constant             Description

 XBP_NO_GROUP     *)  Dialog element does not belong to a group
 XBP_BEGIN_GROUP      Dialog element is the first in a group
                      (this begins the definition of the group)
 XBP_WITHIN_GROUP     Dialog element is within a group
 XBP_END_GROUP        Dialog element is the last in a group
                      (this ends the definition of the group)

*) Default value

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

NAME <cVarName> is the variable name to assign to the GET
object (for HTML based applications.)

RESIZE <aResize> is an optional array of two (2) elements
used for resizing and repositioning the object when the parent
is resized.

NOTE: RESIZE is to be used in conjunction with the RESIZE clause
      of DCGETOPTIONS. See the RESIZE clause of DCGETOPTIONS for
      examples.

      The optional SCALEFONT clause will automatically scale the
      font size up or down when the object is resized.

OPTIONS <nOptions> is a set of options to use to determine the
visual properties of the Radio Button.  The options are numerical
definitions starting with BS_* and are defined in DCDIALOG.CH.

Note the most common option is BS_PUSHLIKE.

DRAG <bDrag> is a codeblock to evaluate when the left mouse button
is clicked in the object and the drag is started.  The return
value of the code block will be stored in memory to be later
retrieved by the Drop operation. A pointer to the clicked on
object is passed to the code block.

DIALOG <bDD> is a codeblock that will evaluate when the drag is
started.  This is used to call a function that will create a
dialog window which will move with the mouse during the drag.
The dialog window will be destroyed upon the drop operation
or the release of the mouse.

Ex: DRAG {|o|o:getData()} DIALOG {|mp1,mp2,oXbp|DragDialog(mp1,mp2,oXbp)} ;

DROP <bDrop> is a codeblock to evaluate when the left mouse button
is released in the object and the drag is ended.  A pointer to
the object and the value stored in memory at the start of the
Drag are passed to the code block.

CURSOR <nDropCursor> is the mouse cursor that will show when it
is moved over this object during a drag operation.

Ex: DROP {|o,x|o:setData(x),o:invalidateRect()} ;
       CURSOR CURSOR POINTER_DATADROP_ASSIGN

SUBCLASS <cSubClass> is a string containing a class name that
will be used to create the class, rather than DC_XbpPushButton().
This class should inherit from DC_XbpActiveXControl().
See the example in \exp19\samples\subclass.

Notes:
 The object created by @ DCRADIOBUTTON is an object of the XbpRadioButton() class, therefore it can be manipulated with any iVar or method supported by XbpRadioButton().

 Radio Button objects are grouped by their parent.  For radio buttons to work properly each group of related radio buttons must have a common parent object.

Examples:
-- Example of GUI radio buttons --

#include "dcdialog.ch"

PROCEDURE Xtest()

LOCAL GetList := {}, cOption

cOption := 'P'

@ 5,10 DCRADIO cOption PROMPT 'Save to Dictionary' VALUE 'D'
@ 5,40 DCRADIO cOption PROMPT 'Save to Source Code' VALUE 'S'
@ 7,10 DCRADIO cOption PROMPT 'Make a Backup file' VALUE 'B'
@ 7,40 DCRADIO cOption PROMPT 'Pack the File' VALUE 'P'

DCREAD GUI ;
   TITLE 'Radio Button Demo' ;
   ADDBUTTONS ;
   FIT

RETURN

-- Example of HTML radio buttons --

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], oForm, cHtml, oTable, cProfession := 'Doctor'

aProfession := { 'Democrat','Republican','HandyMan','Doctor', ;
                 'Plumber','Programmer' }

DCFORM OBJECT oForm
DCTABLE OBJECT oTable PARENT oForm ROWS Len(aProfession) COLUMNS 1

FOR i := 1 TO Len(aProfession)
  @ i,1 DCRADIOBUTTON cProfession VALUE aProfession[i] ;
        PROMPT aProfession[i] PARENT oTable
NEXT

DCREAD HTML TO cHtml

MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:
DCDIALOG.CH

See Also:
   dc_htmlradiobutton()


@ DCRIGHTPRINT SAY

Send right-justified text to printer

@..DCRIGHTPRINT SAY prints text at a specified row and column with the text right justified.

Syntax:

[ @ <nRow>, <nCol> ] DCRIGHTPRINT SAY <uText> ;
   [PICTURE <cPicture>] ;
   [FONT <ocFont>] ;
   [PRINTER <oPrinter>] ;
   [FIXED] ;
   [PIXEL] ;
   [ATTRIBUTE <aAttr>]

Arguments:

<uText> is any variable.

<nRow>, <nCol> are the page coordinates to print the
text.  These are row/column text coordinates unless the
PIXEL parameter was used in the DCPRINT ON command or the PIXEL
argument is passed to the @..DCPRINT SAY command.

FONT <ocFont> is the font to use.  This may be a font object or
a character string containing the font compound name.  If no
font clause is used, then the font selected by the DCPRINT FONT
clause will be the default.

 NOTE: To print with UNDERSCORE, use the word "Underscore" in
       the FONT clause. ex: "12.Arial Bold Underscore".

PICTURE <cPicture> is any picture clause that conforms to the
specification defined in the Xbase++ documentation for the
TRANSFORM() function.

FIXED will print each character of the string on the grid
defined by the SIZE command of the DCPRINT ON command.  FIXED
should be used for numeric columns and strings used as heading
separators like '-------'.

PRINTER <oPrinter> is the printer object returned by the
DCPRINT ON command or the DC_Printer() class.  If this clause
is not used then the printer object referenced by
DC_PrinterObject() is the default.

ATTRIBUTE <aAttr> is an array of attributes that meets the
specification for string attributes such as color, mixmode,
alignment, etc.

<aAttr> := Array( GRA_AS_COUNT )

<aAttr> is an array whose elements contain the attributes for
character strings drawn by the function GraStringAt().

#define constants of the attribute array for character strings.
  These contants are defined in GRA.CH.

 Array element       #define | value     Default value

 GRA_AS_COLOR        GRA_CLR_*           GRA_CLR_NEUTRAL
 GRA_AS_BACKCOLOR    GRA_CLR_*           GRA_CLR_BACKGROUND
 GRA_AS_MIXMODE      GRA_FGMIX_*         GRA_FGMIX_OVERPAINT
 GRA_AS_BGMIXMODE    GRA_BGMIX_*         GRA_BGMIX_LEAVEALONE
 GRA_AS_BOX          { nXsize, nYsize }  dependent on output device
 GRA_AS_ANGLE        { nX, nY }          { 1, 0 }
 GRA_AS_SHEAR        { nX, nY }          { 0, 1 }

 GRA_AS_DIRECTION    GRA_CHDIRN_*        GRA_CHDIRN_LEFTRIGHT
 GRA_AS_HORIZALIGN   GRA_HALIGN_*        GRA_HALIGN_LEFT
 GRA_AS_VERTALIGN    GRA_VALIGN_*        GRA_VALIGN_BASE
 GRA_AS_EXTRA        nExtra              0
 GRA_AS_BREAK_EXTRA  nBreakExtra         0

Notes:

The @..DCPRINT SAY command uses the :AtSay() method of the printer object. This method looks at the current ::nPage instance variable and compares it to the ::nFrom value and the ::nTo value. If the current page is outside the range selected by the user, then no output will be sent to the printer.

Examples:

PROCEDURE XTest()

LOCAL GetList := {}, oBrowse, lDataToolTips := .f., GetOptions

USE COLLECT VIA 'DBFNTX'

@ 0,0 DCBROWSE oBrowse SIZE 60,13 PRESENTATION DC_BrowPres() FIT

DCBROWSECOL FIELD COLLECT->descrip WIDTH 10 PARENT oBrowse ;
   TOOLTIP 'Description' HEADER "Description" DATATOOLTIP {||lDataToolTips}

DCBROWSECOL FIELD COLLECT->type PARENT oBrowse ;
   TOOLTIP 'Type' HEADER "Type"

DCBROWSECOL FIELD COLLECT->memo WIDTH 20 PARENT oBrowse ;
   TOOLTIP 'Memo' HEADER "Memo"  DATATOOLTIP {||lDataToolTips}

DCBROWSECOL FIELD COLLECT->bitmap1 WIDTH 7 PARENT oBrowse ;
   TOOLTIP 'BitMap 1' HEADER "BitMap 1"  ;
   DATATOOLTIP {||lDataToolTips} TIPBLOCK {||_XSample_152(COLLECT->bitmap1)}

DCBROWSECOL FIELD COLLECT->bitmap2 WIDTH 7 PARENT oBrowse ;
   TOOLTIP 'BitMap 1' HEADER "BitMap 2"  ;
   DATATOOLTIP {||lDataToolTips} TIPBLOCK {||_XSample_152(COLLECT->bitmap2)}

@ 14,0 DCCHECKBOX lDataToolTips PROMPT 'Show DataArea Tooltips'

DCGETOPTIONS TOOLTIPCOLOR GRA_CLR_BLACK, GRA_CLR_CYAN

DCREAD GUI FIT MODAL ADDBUTTONS TITLE 'Data Area ToolTips' ;
   OPTIONS GetOptions

CLOSE ALL

RETURN nil

Files:

DCPRINT.CH

See Also:

   @ DCPRINT SAY


@ DCRMCHART

A command interface to RMChart graphing

@ DCRMCHART is a simpler command-based interface to the RMChart ActiveX Control.<br><br>See the sample in .\samples\rmchart\dcchart.prg. New easy to use commands : dcRmchart, dcAddBargroup, dcAddLineGroup, dcAddDataAxis, dcChartregion gives you the power to create complex charts. The include file dcgraph.ch contains the commands you can use.<br><br>More documentation will be provided in a future release.<br><br>

Files:

_dcgraph.prg, dclipx.dll


@ DCRTF

Create a RTF editor object for displaying with GUI reader

The command @..DCRTF creates a RTF Editor object and adds the object to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> @..DCRTF objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCRADIO, @..DCPUSHBUTTON or @..DCMULTILINE.<br><br>

Syntax:

@ <nRow> [,<nCol>]  DCRTF                                          ;
                [VAR <uVar>]                                                ;
                [OBJECT <oObject>]                                          ;
                [SIZE <nWidth> [,<nHeight>]]                                ;
                [PARENT <oParent>]                                          ;
                [PARENTID <cPID>]                                           ;
                [MESSAGE <cMsg> [INTO <oMsg>]]                              ;
                [WHEN <bWhen>]                                              ;
                [HIDE <bHide>]                                              ;
                [HELPCODE <cHelpCode>]                                      ;
                [PRESENTATION <aPres>]                                      ;
                [TITLE <cTitle>]                                            ;
                [TOOLTIP <cToolTip>]                                        ;
                [CURSOR <nCursor>]                                          ;
                [CARGO <xCargo>]                                            ;
                [EVAL <bEval>]                                              ;
                [PREEVAL <bPreEval>]                                        ;
                [POSTEVAL <bPostEval>]                                      ;
                [PIXEL]                              ;
                [RELATIVE <oRel>]                                           ;
                [ID <cId>]                                                  ;
                [ACCELKEY <nAccel>]                                         ;
                [GOTFOCUS <bGotFocus>]                                      ;
                [LOSTFOCUS <bLostFocus>]                                    ;
                [TABSTOP]                     ;
                [NOTABSTOP]              ;
                [TABGROUP <nTabGroup>]                                      ;
                [VISIBLE]                      ;
                [INVISIBLE]               ;
                [GROUP <cGroup>]                                            ;
                [CLASS <bcClass>]                                           ;
                [RESIZE <aReSize> [SCALEFONT]]                        ;
                [APPEARANCE <nAppearance>]                                  ;
                [MAXLENGTH <nMaxLen>]                                       ;
                [RIGHTMARGIN <nRightMargin>]                                ;
                [SCROLLBARS <nScrollBars>]                                  ;
                [POPUPMENU <oPopupMenu>]                                    ;
                [USEPOPUPMENU]      ;
                [BULLETINDENT <nBulletIndent>]                              ;
                [HIDESELECTION]           ;
                [LOCKED]                      ;
                [FILE <cFileName>]                                          ;
                [SELCHANGE <bSelChange>]                                    ;
                [CHANGE <bChange>]  ;                                        ;
                [DRAG <bDrag> [DIALOG <bDD>] ;
                [DROP <bDrop> [CURSOR <nDropCursor>] ;
                [SUBCLASS <cSubClass>]

Arguments:

<nRow>, <nCol> are the coordinates on the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE <oRel> argument is
used.  If no parent is assigned, then the parent is the Dialog
box.  IF the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel
mode by including PIXEL as a command argument.

OBJECT <oObject> is the name of the variable to assign as a
storage place for this object.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

SIZE <nWidth>, <nHeight> defines the size of the object.
If no size is given, then the object will be automatically
sized to fit the caption.  IF the PIXEL option is set to .TRUE.
in DCGETOPTIONS, then the numbers are in pixels otherwise they
are in standard text-based coordinates.  You can also force the
pixel mode by including PIXEL in the command.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object. If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the Static object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

POSTEVAL <bPostEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.
The object is passed as a parameter to the code block.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS

RESIZE <aResize> is an optional array of two (2) elements
used for resizing and repositioning the object when the parent
is resized.

NOTE: RESIZE is to be used in conjunction with the RESIZE clause
      of DCGETOPTIONS. See the RESIZE clause of DCGETOPTIONS for
      examples.

APPEARANCE <nAppearance> determines the appearance ofthe control.
The following options are defined in XBP.CH.

  XBP_APPEARANCE_FLAT   Flat style

  XBP_APPEARANCE_3D *)  Three-dimensional style, object display a 3D border

 *) Default value

MAXLENGTH <nMaxLength> is a numerical value that specifies the maximum
number of characters the XbpRtf object can hold. If the value 0 is
assigned to <nMaxLength> (default), the number of characters that can
be entered into the edit control is not restricted and is limited only
by available memory.

RIGHTMARGIN <nRightMargin> is a numeric value that specifies the right
margin. Text entered into the XbpRtf object is wrapped at or centered
with respect to the margin specified in <nRightMargin> . The value
is interpreted as an offset from the XbpRtf object's right edge.

SCROLLBARS <nScrollBars> is a numeric value used to determine the
scrollbars on the object.

  Constant             Description

  XBP_SCROLLBAR_NONE   No scroll bar is displayed

  XBP_SCROLLBAR_HORIZ  Horizontal scroll bar is displayed if text
                       buffer is wider than can be displayed

  XBP_SCROLLBAR_VERT   Vertical scroll bar is displayed if text buffer
                       has more lines than fit into display area

The contants XBP_SCROLLBAR_HORIZ and XBP_SCROLLBAR_VERT can be combined
to have the XbpRtf object display both a horizontal and a vertical scroll
bar, if required. To do that, the contants must be added.

POPUPMENU <oPopupMenu> contains an object derived from the XbpMenu class.
The menu object is used to display a popup menu if the user presses the
right mouse button over the edit control. The menu is opened also if the
SHIFT+F10 key combination is entered. If <oPopupMenu> contains the value
NIL, a default menu is used that contains menu items for copying, pasting
and deleting text.

The display of the object's popup menu can be switched off by assigning
the value .F. (FALSE) to the instance variable :usePopupMenu.

BULLETINDENT <nBulletIndent> defines the indentation used for paragraphs
preceeded by a bullet. To preceeded a paragraph with a bullet, the
:selBullet instance variable must be set to .T. (TRUE).

HIDESELECTION The specifies whether selected text should remain
highlighted when the XbpRtf object loses the input focus. Per default,
selected text is displayed highlighted only when the edit control has
input focus. To change that behviour, an Xbase++ application can assign
the value .F. (FALSE) to the :hideSelection instance variable.

LOCKED or the :locked instance variable specifies whether the XbpRtf
object is currently locked. If .T. (TRUE) is assigned to this instance
variable, text in the edit control cannot be edited.

Note: The value contained in :locked superceeds that in the :selReadOnly
instance variable. If :locked is TRUE, the text cannot be edited,
irrespective of the value assigned to :selReadOnly .

FILE <cFileName> is the name of the file to load into the RTF control.

SELCHANGE <bSelChange> is a callback codeblock {| uNIL1, uNIL2, self | ... }
to evaluate when the contents of the XbpRtf object's text buffer changes.
This usually indicates that the user has moved the cursor in the text buffer.

CHANGE <bChange> is a callback codeblock {| uNIL1, uNIL2, self | ... }
to evaluate when the selection in the text buffer is changed.

DRAG <bDrag> is a codeblock to evaluate when the left mouse button
is clicked in the object and the drag is started.  The return
value of the code block will be stored in memory to be later
retrieved by the Drop operation. A pointer to the clicked on
object is passed to the code block.

DIALOG <bDD> is a codeblock that will evaluate when the drag is
started.  This is used to call a function that will create a
dialog window which will move with the mouse during the drag.
The dialog window will be destroyed upon the drop operation
or the release of the mouse.

Ex: DRAG {|o|o:getData()} DIALOG {|mp1,mp2,oXbp|DragDialog(mp1,mp2,oXbp)} ;

DROP <bDrop> is a codeblock to evaluate when the left mouse button
is released in the object and the drag is ended.  A pointer to
the object and the value stored in memory at the start of the
Drag are passed to the code block.

CURSOR <nDropCursor> is the mouse cursor that will show when it
is moved over this object during a drag operation.

Ex: DROP {|o,x|o:setData(x),o:invalidateRect()} ;
       CURSOR CURSOR POINTER_DATADROP_ASSIGN

SUBCLASS <cSubClass> is a string containing a class name that
will be used to create the class, rather than DC_XbpRtf().
This class should inherit from DC_XbpRtf().
See the example in \exp19\samples\subclass.

Notes:

The object created by @ DCRTF is an object of the XbpRTF() class, therefore it can be manipulated with any iVar or method supported by XbpRTF().

Examples:

See the example in SAMPLES\RTF

Files:

DCDIALOG.CH


@ DCSAY GET

Create a SAY..GET object for displaying with the text/GUI reader

The command @..DCSAY...GET creates a new Get object and adds the object to the array named GETLIST which is later processed by the DC_Read*() functions or by the DCREAD * commands.<br><br> The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the the edit mode for all Get objects found in the GetList array. The command DCREAD HTML writes the HTML source code to render the objects in a Web Browser. A Get object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> @..DCSAY..GET works nearly identical to the standard Xbase++ command @..SAY..GET except for a major difference. The GetList array has a new structure that supports a more robust dialog system. This GetList is then passed to the function DC_ReadGui() which creates the objects and starts an event handler, or the GetList can be be passed to the function DC_ReadHtml() which creates the objects and writes HTML source.<br><br> The command is broken into 2 sections to prevent problems with the Microsoft Help Compiler. See @ .. DCSAY .. GET (2)

Syntax:

@ <nSayRow>,<nSayCol> DCSAY <bcText> ;
    [GET <uVar>] ;
    [SAYVAR <uSayVar>], ;
    [GETPOS <nGetRow> [,<nGetCol>] ] ;
    [DATALINK <bLink>] ;
    [SAYCOLOR <bncSayFgC>,[<ncSayBgC>] ] ;
    [GETCOLOR <bncGetFgC>,[<ncGetBgC>] ] ;
  * [SAYSIZE <nSayWidth> [,<nSayHeight>]] ;
  * [GETSIZE <nGetWidth> [,<nGetHeight>]] ;
    [SAYFONT <bocSayFont>] ;
    [GETFONT <bocGetFont>] ;
    [PARENT <oParent>] ;
    [PARENTID <cParentId>] ;
    [MESSAGE <bcMsg> [INTO <oMsgBox>]] ;
    [VALID <bValid>] ;
    [NOEXITVALID <bValid>] ;
  * [UNREADABLE] ;
  * [CONFIRM] ;
  * [NOCONFIRM] ;
    [POPUP <bPopUp> ;
       [POPCAPTION <ncCaption] ;
       [POPFONT <cPopFont>] ;
       [POPWIDTH <nPopWidth>] ;
       [POPHEIGHT <nPopHeight>] ;
       [POPSTYLE <nPopStyle>] ;
       [POPKEY <anPopKey>] ;
       [POPTABSTOP] ;
       [POPGLOBAL] ] ;
       [POPTOOLTIP <bcPopToolTip>] ;
       [POPWHEN <bPopWhen>] ;
       [POPHIDE <bPopHide>] ;
  * [PROPER ;
       [PROPOPTIONS <aPropOptions>]] ;
    [PASSWORD [PASSCHAR <cPassChar>] [SHOWLASTCHAR] ;
    [WHEN <bWhen>] ;
    [HIDE <bHide>] ;
  * [EDITPROTECT <bProtect>] ;
  * [SAYOPTIONS <nSayOpt> | SAYRIGHT | SAYLEFT | SAYCENTER]  ;
    [ALIGNRIGHT] ;
    [HELPCODE <cHelp>] ;
  * [PICTURE <bcPicture>] ;
  * [PIXEL] ;
  * [SAYPRESENTATION <aSayPres>] ;
  * [GETPRESENTATION <aGetPres>] ;
    [SAYTOOLTIP <bcSayToolTip>] ;
    [GETTOOLTIP <bcGetToolTip>] ;
    [SAYOBJECT <oSayObject>] ;
    [GETOBJECT <oGetObject>] ;
  * [SAYCURSOR <naSayCursor>] ;
  * [GETCURSOR <naGetCursor>] ;
    [SAYCARGO <xSayCargo>] ;
    [GETCARGO <xGetCargo>] ;
    [RELATIVE <oRel>] ;
    [SAYID <cSayId>] ;
    [GETID <cGetId>] ;
    [SAYTITLE <cSayTitle>] ;
    [GETTITLE <cGetTitle>] ;
  * [ACCELKEY <anAccel>] ;
  * [GOTFOCUS <bGotFocus>] ;
  * [LOSTFOCUS <bLostFocus>] ;
  * [TABSTOP]  ;
  * [NOTABSTOP];
  * [TABGROUP <nTabGroup>] ;
  * [VISIBLE] ;
  * [INVISIBLE] ;
    [GROUP <cGroup>] ;
  * [KEYBLOCK <bKeyBlock>] ;

    <more clauses... See @ DCSAY GET (2)

Arguments:

GUI applications:

<nSayRow> and <nSayCol> are the row and column of the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE <oRel> argument is
used.  If no parent is assigned, then the parent is the Dialog
box. IF the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel
mode by including PIXEL as a command argument.

<nSayRow> may be assigned the value DCGUI_ROW.  This will paint
the object at the same row as the previous object.  It is
provided to emulate the Row() function in text-based applications.

<nSayCol> may be assigned the value DCGUI_COL + <nOffset>.  This
will paint the object immediately to the right of the previous
object plus <nOffset> pixels.  It is provided to emulate the Col()
function in text-based applications.

HTML applications:

<nRow> and <nCol> are the row number and column number of
the table if the parent of this object is a DCTABLE. The
text will be inserted in the cell of the table defined by
the row/column.

<bcText> is the text to display in front of the GET.  This may be
a character string or a code-block which returns a character
string.  If it is a code-block, it is refreshed with the function
DC_GetRefresh().

GET <uVar> is the variable to GET.  This may be a variable
of any type except an object or array. It must not be a macro.
The <uVar> is automatically anchored via a Get-Set codeblock
created by DC_GetAnchorCB() unless <uVar> is a custom Get-Set
code block.  Macros may be used in a custom Get-Set code block.

SAYVAR <bcSayVar> is the name of a character-type variable
or a Set Code Block which will may used to set the caption of
the SAY text when the Get List is refreshed with DC_GetRefresh().

DATALINK <bLink> is an optional code block that is evaluated
every time Get/Set codeblock is evaluated, ie when the data
is read from the <uVar> into the object except when using
a user-defined Get/Set code block.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

GETPOS <nGetRow>, <nGetCol> are the "optional" coordinates
of the GET.  If no argument is used, then the GET will be
placed at the end of the SAY string.

SAYCARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for the SAY object.

GETCARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for the GET object.

The cargo may be accessed at any time via the :cargo exported
variable, however it will not be stored in the same manner it is
entered.  The :cargo container of DCDIALOG objects is an array of
at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

SAYSIZE <nSayWidth> [,<nSayHeight>]] is the size to allocate to
the SAY string.  If the PIXEL option is set to .TRUE. in
DCGETOPTIONS, then the size must be entered in pixels otherwise
it must be entered in standard text length.  If no SAYSIZE
argument is used, then the say will be automatically sized to
the size established by the SAYSIZE option of the DCGETOPTIONS
command.  SAYSIZE 0 will automatically size the SAY (XbpStatic)
object to the size of the text taking into consideration the
selected font.

GETSIZE <nGetWidth> [,<nGetHeight>]] is the size to
allocate to the GET variable.  If the PIXEL option is set to
.TRUE. in DCGETOPTIONS, then the size must be entered in
pixels otherwise it must be entered in standard text
length.  If no GETSIZE argument is used or GETSIZE is ZERO, then
the get will be automatically sized to the size established by
transforming the contents of of the get variable to a string to
determine the length of the get.   The default font for GETS in
eXpress++ is 8.Courier because this provides the best user
font for data-entry, so it is usually not necessary to use
this option unless you are also using the GETFONT parameter.

SAYFONT <bocSayFont> is a character string defining an optional
font for the SAY text.  The font string must conform to the
Xbase++ standard, ie. "10.Courier.Bold.  It may also be a font
object or a code block that returns a character string or a
font object to later refresh with DC_GetRefresh().

GETFONT <bocGetFont> is a character string defining an optional
font for the GET text.  The font string must conform to the
Xbase++ standard, ie. "10.Courier Bold".  The default is
"8.Courier". It may also be a font object or a code block that
returns a character string or a font object to later refresh
with DC_GetRefresh().

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.  If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

MESSAGE <bcMsg> is the message you want to display in the
message area of the dialogue screen defined by the DCMESSAGEBOX
command when the object is in focus.  Optionally, INTO <oMsgBox>
will designate which message box to display the message into.
If the INTO clause is not used, then the last message box in the
GetList is the default.  <oMsgBox> may also be any object that
supports the :setCaption() method.  If <bcMsg> is a code-block,
it must return a character string.

PICTURE <bcPicture> is a character string specifying formatting
options for the value of <VarName> during display and editing.
If <bcPicture> is a code block, then the code block must return
a character string.  The code block is evaluated by the DC_GetRefresh()
function.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the GET object will be disabled and
grayed. If the value returned is .TRUE. then the object will be
enabled. The object is passed as a parameter to the code block.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.
The object is passed as a parameter to the code block.

EDITPROTECT <bProtect> is an optional condition tested during the
execution of the GUI gets by the DCREAD GUI command, before the
object receives input focus (before it is activated). When the
condition returns the value .F. (false), the object receives the
input focus.  Otherwise, it is skipped. <bProtect> is a code
block that must return a logical value when evaluated. The code
block is evaluated prior to the object receiving input focus.
This clause behaves similar to the WHEN clause with the exception
that the object is not disabled (grayed out).  The object is
passed as a parameter to the code block.

The UNREADABLE clause will cause text to be displayed as asterisks
(*) for inputting sensitive data such as passwords.

The NOCONFIRM clause will cause the GET to be exited when the
cursor reaches the end of the buffer during keyboard entry.
Normally, the GET can be exited only by pressing the ENTER key,
TAB key, UP key, DOWN key or clicked on another object.  This
overrides the setting of CONFIRM in DCGETOPTIONS.

The CONFIRM clause will cause the GET to be exited by pressing
the ENTER key.  This overrides the setting of NOCONFIRM in
DCGETOPTIONS.

VALID <bValid> is an optional condition tested during the
execution of the GUI gets by the READ command before a Get
object loses input focus (before it is deactivated).  When
the condition returns the value .T. (true), the Get object
loses the input focus.  Otherwise, it remains active. <bValid>
is a code block that must return a logical value when it is
evaluated.  The object is passed as a parameter to the code block.
Note: To exit a dialog with a pushbutton and insure that the
validation code block is not evaluated, use the clause
CARGO 'CANCEL' with the DCPUSHBUTTON command.

NOEXITVALID <bValid> is a replacement for the VALID clause.
This will insure that the <bValid> codeblock is only validated
upon lost focus, and NOT validated with the EXITVALIDATE clause
of DCGETOPTIONS.

HELPCODE <cHelp> is a character string that is passed to the
DC_HelpF1() function if F1 is pressed or the HELP button
is clicked when this GET has focus.  This HELPCODE allows
the Help system to override the passing of the Procedure and
Varname for more specific context-help.

AUTOSIZE automatically sizes the SAY string object to the
length of the string.

POPUP <bPopUp> will paint a mouse button at the end of the GET
variable on the screen which informs the operator than an
additional picklist will pop-up if the operator single-clicks on
the button or if the operator presses the CTRL-J or CTRL-ENTER
key while the GET has input focus.  The code block will be
evaluated when the button is clicked.  The following tw0
parameters are passed to the codeblock :

  1. The value in the current GET
  2. A pointer to the GET object

The value returned by the code block will be placed back in the
GET.  The code block may return an optional array of two
elements rather than a single value to store to the GET.  If a
two-element array is returned, the first element must be the
value to store in the GET and the second element must be a
pointer to the object which is to receive focus. This provides
for the ability to force the focus to a different object on a
POPUP other than the GET.

The POPUP clause is used for popups like calendars, calculators,
picklists, etc.  The default caption on the button is three dots.
To change the caption or button display options, use the
function DC_GetPopupCaption().

POPCAPTION <ncaCaption> is the optional caption of the button.
This will override the DC_PopupCaption() setting.   This will override the
DC_GetPopupCaption() setting. If <ncaCaption> is an array, it
must be an array of 2 elements where the first element is the
bitmap resource number of the caption to display when the GET is
enabled and the second element is the bitmap resource number of
the caption to display when the GET is disabled with the WHEN
clause.

POPFONT <cFont> is the optional font of the button.

POPWIDTH <nWidth> is the width (in pixels) of the button.  This
will override the default width.

POPHEIGHT <nHeight> is the height (in pixels) of the button.
This will override the default height.

POPSTYLE <nPopStyle> is the style of the popup button:

  POPSTYLE <nPopStyle>       Description
  -------------------------  ----------------------------------
  DCGUI_POPUPSTYLE_OUTSIDE   Button is outside and to the right
                             of the GET.
  DCGUI_POPUPSTYLE_IMBEDDED  Button is imbedded within the GET.

POPKEY <anPopKey> is a numeric key value or an array of numeric
key values that may be assigned to invoke the popup button when
the key is pressed.  An additional POPGLOBAL clause may be used
to establish that the assigned key is active regardless of the
object that is in focus, otherwise the key will be active only
when the associated get has focus.  Key values are defined in
APPEVENT.CH and start with the definition xbeK_*.

POPTABSTOP will cause the TABSTOP key to be active on the popup
button so the user may tab from the GET to the popup button.

POPTOOLTIP <bcPopToolTip> is a character string which will display
as a "Tool Tip" next to the popup button the mouse is passed
over the popup button. A semi-colon within the text indicates a new
line.  If <bcToolTip> is a code-block, it must return a character
string.  NOTE: The Tooltip painting method is run in another
thread, therefore the codeblock should not run code that points
to the current work area.  It may however, contain local, public
or private variables.

POPWHEN <bPopWhen> is a code block to evaluate to determine
whether the popup button is enabled or disabled.  If the codeblock
returns a .T., then the button is enabled, otherwise it is
disabled.

POPHIDE <bPopHide> is a code block to evaluate to determine
whether the popup button is hidden.  If the codeblock returns
a .T. then the button is hidden.

PASSWORD will cause asterisks to be displayed in place of the
value entered.  This only affects the display, not the value
entered or returned.  PASSCHAR is an optional clause to define
the character to be used as a replacement for the asterisk.
SHOWLASTCHAR is an optional clause which will show the actual
last character entered.

PROPER will cause the first character of each word to be
capitalized and all other characters to be lower case.  The
optional clause PROPOPTIONS designates a two element array
for alternate behavior:

{ lProperLow, cTriggers }

lProperLow - Logical.  Force upper case characters to lower case
             If not First character in field or following trigger
             character.

cTriggers  - A list of characters after which a capital is desired.
             (ie. " '-1234567890" capitalize after space, apostrophe,
             hyphen, or any number)

SAYPRESENTATION <aSayPres> is a two-dimensional array. If
specified, this contains presentation parameters for the SAY
object.  The first column of the array must contain #define
constants from the XBP.CH file starting with the prefix
XBP_PP_. These constants define the presentation parameters
that can be set for the object and include colors and fonts.
The second column of the array in <aSayPres> contains the value
for each setting.  These are also generally set using #define
constants from the GRA.CH file.

GETPRESENTATION <aGetPres> is a two-dimensional array. If
specified, this contains presentation parameters for the GET
object.  The first column of the array must contain #define
constants from the XBP.CH file starting with the prefix
XBP_PP_. These constants define the presentation parameters
that can be set for the object and include colors and fonts.
The second column of the array in <aSayPres> contains the value
for each setting.  These are also generally set using #define
constants from the GRA.CH file.

SAYOPTIONS <nSayOpt> is a set of options that can be used to
align the text within the rectangular area of the SAY object.
Constants defined in the XBP.CH file are used for these options.
If combinations of alignment options are required, the sum of
the appropriate constants must be included in <nSayOpt>.
The below constants are defined in XBP.CH.

 XBPSTATIC_TEXT_LEFT       Text is left aligned
 XBPSTATIC_TEXT_CENTER     Text is horizontally centered
 XBPSTATIC_TEXT_RIGHT      Text is right aligned
 XBPSTATIC_TEXT_TOP        Text is displayed at top
 XBPSTATIC_TEXT_VCENTER    Text is vertically centered
 XBPSTATIC_TEXT_BOTTOM     Text is displayed at bottom
 XBPSTATIC_TEXT_WORDBREAK  Text is wrapped (multi-line)

 An alternate method of aligning text is by using the following
 defines in place of SAYOPTIONS <nSayOpt>:

 SAYRIGHT
 SAYLEFT
 SAYRIGHTBOTTOM
 SAYLEFTBOTTOM
 SAYCENTERBOTTOM
 SAYRIGHTCENTER
 SAYLEFTCENTER
 SAYRIGHTTOP
 SAYLEFTTOP
 SAYCENTER
 SAYHCENTER
 SAYBOTTOM
 SAYBOTTOMLEFT
 SAYBOTTOMRIGHT
 SAYTOP
 SAYTOPCENTER
 SAYVCENTER
 SAYHVCENTER
 SAYWORDBREAK

ALIGNRIGHT causes the end of the SAY object to align with the
column given rather than the start of the SAY object.

SAYTOOLTIP <bcSayTool> is a character string which will display
as a "Tool Tip" next to the object when the cursor is passed
over the Say object. A semi-colon within the text indicates a new
line.  If <bcToolTip> is a code-block, it must return a character
string.  NOTE: The Tooltip painting method is run in another
thread, therefore the codeblock should not run code that points
to the current work area.  It may however, contain local, public
or private variables.

GETTOOLTIP <bcGetTool> is a character string which will display
as a "Tool Tip" next to the object when the cursor is passed
over the Get object. A semi-colon within the text indicates a new
line.  If <bcToolTip> is a code-block, it must return a character
string.  NOTE: The Tooltip painting method is run in another
thread, therefore the codeblock should not run code that points
to the current work area.  It may however, contain local, public
or private variables.

SAYOBJECT <oSayObject> is the name of the variable to store a
pointer to the SAY object after it is created.

GETOBJECT <oGetObject> is the name of the variable to store a
pointer to the GET object after it is created.

SAYCURSOR <nSayCursor> is an optional mouse pointer to use for
the SAY portion of the SAY..GET.  System mouse pointers start
with XBPWINDOW_POINTERTYPE_  and are defined in XPB.CH.  The
default pointer is XBPWINDOW_POINTERTYPE_POINTER.  <nCursor> may
also be a resource ID that points to a Bit-Map that has been
compiled with the resource compiler and linked to the .EXE.

GETCURSOR <naGetCursor> and SAYCURSOR <naSayCursor> may be either
a numeric value or an array of 3 elements which defines an
optional mouse pointer to use for this object.  System mouse
pointers start with XBPWINDOW_POINTERTYPE_ and are defined in
XPB.CH.  The default pointer is XBPWINDOW_POINTERTYPE_POINTER.
<naGetCursor> / <naSayCursor> may be a numeric resource ID that
points to a Bit-Map that has been compiled with the resource
compiler and linked to the .EXE. <naGetCursor> / <naSayCursor>
may be a 3-element array described as follows:

  Element  Type  Description
  -------  ---- ---------------------------------------------
    [1]      C   Optional name of .DLL containing the pointer
                 resource.

    [2]      N   The numeric resource ID of the pointer.  If
                 element 1 is a NIL, then this resource must be
                 linked into the .EXE.

    [3]      N   The type of resource as defined in XBP.CH.

SAYCOLOR <bncSayFGc>, <ncSayBGc> are foreground and background
colors for the SAY text. They may be character strings
representing valid text-based colors supported by SetColor() or
they may be numeric constants which begin with either the prefix
GRA_CLR_ or the prefix XBPSYSCLR_ as defined in GRA.CH or XBP.CH.
If <bncSayFGc> is a code block is must return a 2-element array
containing a foreground and background color.

GETCOLOR <bncGetFGc>, <ncGetBGc> are foreground and background
colors for the GET. They may be character strings representing
valid text-based colors supported by SetColor() or they may be
numeric constants which begin with either the prefix GRA_CLR_ or
the prefix XBPSYSCLR_ as defined in GRA.CH or XBP.CH. If
<bncGetFGc> is a code block is must return a 2-element array
containing a foreground and background color.

SAYID <cSayId> is a unique identifier for the SAY portion of this
object.  This ID is used with functions like DC_GETOBJECT() to
determine the status of a getlist object.

GETID <cGetId> is a unique identifier for the GET portion of this
object.  This ID is used with functions like DC_GETOBJECT() to
determine the status of a getlist object.

ACCELKEY <anAccel> is a numeric "hot-key" assignment that will set
focus to the checkbox object when the hot-key is pressed.  The key
must be a valid key with the prefix xbeK_*.  These keys are
defined in APPEVENT.CH.  <anAccel> may also be an array of numeric
values to assign more than one key to the object.

GOTFOCUS <bGotFocus> is a code block that is evaluated when the
GET object receives input focus.  <bGotFocus> := {|uNIL1,uNIL2,self|...}

LOSTFOCUS <bLostFocus> is a code block that is evaluated when the
GET object loses input focus  .<bLostFocus> := {|uNIL1,uNIL2,self|...}

TABSTOP will cause the object (Xbase Part) to be set when using
the Tab key.  Note: When logical groups are defined in a dialog
using TABGROUP <nTabGroup>, TABSTOP is usually set to .T. (true)
for the first dialog element in the group.  This allows the first
dialog element of a group to be activated using the Tab key.

NOTABSTOP will cause the object (Xbase Part) to be ignored when
using the Tab key. This clause is needed only to override any
default setting of TabStop by the DCGETOPTIONS [TABSTOP] command.

TABGROUP <nTabGroup> allows objects (Xbase Parts) that are created
immediately after one another in the GetList to be combined into
logical groups. This allows the user to navigate within a dialog
from group to group by pressing the Tab key.  Within a group of
dialog elements navigation is performed using the cursor keys.

Only constants defined in the XBP.CH file can be used as values
for this instance variable.  The following table lists the
available constants:

#define constants for <nTabGroup>:

 Constant             Description

 XBP_NO_GROUP     *)  Dialog element does not belong to a group
 XBP_BEGIN_GROUP      Dialog element is the first in a group
                      (this begins the definition of the group)
 XBP_WITHIN_GROUP     Dialog element is within a group
 XBP_END_GROUP        Dialog element is the last in a group
                      (this ends the definition of the group)

*) Default value

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS.

KEYBLOCK <bKeyBlock> is a code block to evaluate when a key is
pressed in the GET.  The code block should be formatted as follows:
{|mp1,xNil,oXbp|MyFunc(mp1,xNil,oXbp)} where <mp1> is the
numeric value (defined in APPEVENT.CH) of the key pressed and
oXbp is the GET object.

Notes:

Clauses marked by an asterisk ( * ) are not supported by DCREAD HTML or DC_ReadHtml().

------------------

GUI applications:

The SAY object created by @ DCSAY..GET is an object of the DC_XbpStatic() class unless the GRASTRING clause is used. The GRASTRING clause causes the say to be painted by the GraStringAt() function and does not create an object. DC_XbpStatic() inherits from XbpStatic()

The GET object created by @ DCSAY..GET is an object of the DC_XbpGet() class, therefore it can be manipulated with any iVar or method supported by DC_XbpGet(). DC_XbpGet() is a non-supported class which is provided with Xbase++ as an example. This class inherits from the XbpSle() class and the Get() class. It has been modified to support features required by eXPress++. The source for DC_XbpGet() is in _DCXBPGT.PRG.

If the CHECKGET option of GETOPTIONS is used, then the GET object is an object of the DC_XbpCheckBox() class.

-----------------

HTML Applications

The SAY object created by @ DCSAY..GET is an object of the DC_HtmlSay() class.

The GET object created by @ DCSAY..GET is an object of the DC_HtmlGet() class.

Examples:

/*  Example 1 (Simple Gets) */

#include "dcdialog.ch"

PROCEDURE Xtest_1()

LOCAL GetList := {}, cLastName := Space(15), cFirstName := Space(15),;
      cCompany := Space(25), cStreet := Space(25), cCity := Space(25),;
      cState := Space(2), cCountry := Space(20), cPhone := Space(15),;
      GetOptions

@ 5,10 DCSAY ' Last Name' GET cLastName
@ 5,40 DCSAY 'First Name' GET cFirstName
@ 7,10 DCSAY '   Company' GET cCompany
@ 8,10 DCSAY '    Street' GET cStreet
@ 9,10 DCSAY '      City' GET cCity
@11,10 DCSAY '     State' GET cState
@11,40 DCSAY '   Country' GET cCountry
@13,10 DCSAY '     Phone' GET cPhone PICT '(999)-999-9999'

DCGETOPTIONS SAYRIGHTJUST

DCREAD GUI ;
    FIT ;
    ADDBUTTONS ;
    OPTIONS GetOptions

RETURN

/*  Example 2 (Gets with Whens, Hides, Validations and Pop-ups)  */

PROCEDURE Xtest_2()

LOCAL GetList := {}, cLastName := Space(15), cFirstName := Space(15),;
      cCompany := Space(25), cStreet := Space(25), cCity := Space(25),;
      cState := Space(2), cCountry := Space(20), cPhone := Space(15),;
      dDate1 := Date(), dDate2 := Date()+1, GetOptions

@ 5,10 DCSAY ' Last Name' GET cLastName ;
       VALID {||DC_ReadEmpty(cLastName)}

@ 5,40 DCSAY 'First Name' GET cFirstName ;
       VALID {||DC_ReadEmpty(cFirstName)}

@ 7,10 DCSAY '   Company' GET cCompany

@ 8,10 DCSAY '    Street' GET cStreet ;
       VALID {||DC_ReadEmpty(cStreet)}

@ 9,10 DCSAY '      City' GET cCity ;
       VALID {||DC_ReadEmpty(cCity)}

@11,10 DCSAY '     State' GET cState PICT '@!' ;
       VALID {||DC_ReadEmpty(cState)} ;
       WHEN {||!Empty(cCity)}

@11,40 DCSAY '   Country' GET cCountry

@13,10 DCSAY '     Phone' GET cPhone PICT '(999)-999-9999'

@15,10 DCSAY 'Start Date' GET dDate1 ;
       POPUP {|d|DC_PopDate(d)}

@16,10 DCSAY '  End Date' GET dDate2 ;
       HIDE {||dDate1 = Date()}

DCGETOPTIONS SAYRIGHTJUST

DCREAD GUI ;
    FIT ;
    ADDBUTTONS ;
    OPTIONS GetOptions

RETURN

/* Example 3

  This example shows @ DCSAY..GETs which do direct edits into a
  database.  The GET variable is a code-block that automatically
  handles locking/unlocking and macros.  In this example, all
  screen dialog is data-driven. */

 LOCAL GetList := {}, aData, i, bBlock, bValid, bWhen

 CLOSE ALL
 USE COLLECT NEW EXCL

 aData := { { 1, 1, 'Description', 'COLLECT->descrip', '@!', ;
                    '!Empty(COLLECT->descrip)', '.T.' }, ;
            { 3, 1, 'Original Price', 'COLLECT->orig_price', '9999.99', ;
                    '.T.','.T.'}, ;
            { 5, 1, 'Date Acquired', 'COLLECT->date_acqu', '', ;
                    '.T.', '.T.' } }

 FOR i := 1 TO Len(aData)

   bBlock := _XTest3(aData[i,4],1)
   bValid := _XTest3(aData[i,6],2)
   bWhen  := _XTest3(aData[i,7],2)

   @ aData[i,1], aData[i,2] DCSAY aData[i,3] GET bBlock ;
     PICTURE aData[i,5] ;
     VALID bValid ;
     WHEN bWhen ;
     SAYRIGHT ;
     SAYSIZE 15

 NEXT

 DCREAD GUI FIT ADDBUTTONS

RETURN nil

/* -------------------- */

STATIC FUNCTION _XTest3( xValue, nMode )

IF nMode = 1 // Field Anchor
  RETURN {|x|IIF(x==nil,&xValue,IIF(dbRLock(),&xValue:=x,nil)), ;
             IIF(!(x==nil),dbUnlock(),nil),&xValue }
ENDIF

RETURN {||&xValue}  // VALID or WHEN Anchor

/* Example 4 - This example shows @ DCSAY..GET ... COMBO. */

PROCEDURE XTest_5()

LOCAL GetList := {}, cCode, aCodes, aCodeDesc

aCodes := { 'A','B','C'}

aCodeDesc := { 'Selection A', ;
               'Selection B', ;
               'Selection C' }

cCode := aCodes[1]

@ 1,1 DCSAY 'Enter Code' GET cCode GETSIZE 15 ;
      COMBO HEIGHT 6 DATA aCodeDesc RETURN {|n|aCodes[n]}

DCREAD GUI FIT ADDBUTTONS TITLE 'Combo Test'

RETURN

Files:

DCDIALOG.CH

See Also:

   @ DCSAY GET (2)
   dc_getpopupcaption()
   @ DCGET
   dc_getcombomode()


@ DCSAY GET (2)

Create a SAY..GET object for displaying with the text/GUI reader

<< continued from @ DCSAY GET >> <br><br> The command @..DCSAY...GET creates a new Get object and adds the object to the array named GETLIST which is later processed by the DC_Read*() functions or by the DCREAD * commands.<br><br> The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the the edit mode for all Get objects found in the GetList array. The command DCREAD HTML writes the HTML source code to render the objects in a Web Browser. A Get object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> @..DCSAY..GET works nearly identical to the standard Xbase++ command @..SAY..GET except for a major difference. The GetList array has a new structure that supports a more robust dialog system. This GetList is then passed to the function DC_ReadGui() which creates the objects and starts an event handler, or the GetList can be be passed to the function DC_ReadHtml() which creates the objects and writes HTML source.<br><br>

Syntax:

  << continued from @ DCSAY GET >>

  * [COMBO ;
       [HEIGHT <nComboHeight>] ;
       [WIDTH <nComboWidth>] ;
       [DATA <acbComboData>]        ;
       [FIELD <bField>] ;
       [ELEMENT <nElement>] ;
       [RETURN <bReturn>] ;
       [CAPTION <oncComboCaption>] ;
       [FONT <ocComboButtonFont>] ;
       [LISTFONT <ocComboListFont>] ;
       [LISTPRESENTATION <aListPres>] ;
       [HOTKEY <nComboHotKey>] ] ;
       [KEYDROP] ;
  * [GRASTRING] ;
    [NAME <cVarName>] ;
  * [HYPERLINK <bHyperLink>] ;
  * [CALCULATOR] ;
    [SAYRESIZE <aSayResize> [SCALEFONT] ] ;
    [GETRESIZE <aGetResize> [SCALEFONT] ] ;
    [SAYDRAG <bSayDrag> [DIALOG <bSayDD>] ;
    [SAYDROP <bSayDrop> [CURSOR <nSayDropCursor>]
    [GETDRAG <bGetDrag> [DIALOG <bGetDD>] ;
    [GETDROP <bGetDrop> [CURSOR <nGetDropCursor>] ;
    [SAYSUBCLASS <cSaySubClass>] ;
    [GETSUBCLASS <cGetSubClass>] ;
    [FORMATTED] ;
    [GETALIGN <nGetAlign>] ;
    [SAYPREEVAL <bSayPreEval>] ;
    [GETPREEVAL <bGetPreEval>] ;
    [SAYEVAL <bSayEval,...>] ;
    [GETEVAL <bGetEval,...>] ;

Arguments:

COMBO is used to create a ComboBox-Style Get with a pull-down
picklist from an array or database.  HEIGHT <nComboHeight> is
the Height of the Picklist area in text rows or in pixels if
the PIXEL clause is used.  WIDTH <nComboWidth> is the width of the
picklist area in text columns or in pixels if the PIXEL clause is
used.  If the WIDTH clause is not used, then the width of the
picklist will be the same as the width of the Get.  DATA <acbComboData>
is the data source of the picklist.  <acbComboData> must be a
character string containing the Alias() of the database, a
single-dimension array, a multi-dimensional array or a code-block
which returns an alias or array. FIELD <bField> is a code block
containing the field name of the data to be shown in the picklist
(when browsing a database) or ELEMENT <nElement> is the numeric
value of the column in the array to be shown in the picklist (when
browsing an array). RETURN <bReturn> is a code block to evaluate on
return.  CAPTION <oncComboCaption> is the caption to place on the
popup button that invokes the listbox.  This may be a character
string, a numeric resource, or an XbpBitMap() object.
FONT <ocComboButtonFont> is the font to use for the pushbutton
(if the caption is a character string).  LISTFONT <ocComboListFont>
is the font to use for the listbox.  LISTPRESENTATION <aComboListPres>
is a presentation array defining the presentation parameters for
the listbox.  HOTKEY <nComboHotKey> is the hot key to use to invoke
the listbox. KEYDROP will cause the combobox to drop down on
pressing the first key in the GET.

GRASTRING will use the GraStringAt() function to paint the SAY
portion rather than an XbpStatic() object.  This uses less
memory resources.  Note: because an object does not exist, the
say text cannot be manipulated at run time.

CAUTION: Do not use GRASTRING clause with the FIT clause of
         DCREAD GUI or the AUTORESIZE clause of DCGETOPTIONS,
         unless the DCGRA* object is drawn on an object that
         does not get resized or repositioned at a later time.
         Auto-Sizing and Auto-Fitting is accomplished by
         traversing child list of the Parent object and reading
         the size and/or coordinates of all objects.  DCGRA*
         commands are not objects, therefore they cannot be
         repositioned correctly.

SAYPREEVAL <bSayPreEval> is a code block to be evaluated by the
GUI reader before the SAY object is created.  The object is
passed to the code block.

SAYEVAL <bSayEval> is a code block to evaluate after the SAY
object is created.  The XbpStatic object will be passed to the
code block.

GETPREEVAL <bGetPreEval> is a code block to be evaluated by the
GUI reader before the GET object is created.  The object is
passed to the code block.

GETEVAL <bGetEval> is a code block to evaluate after the GET
object is created.  The XbpGet object will be passed to the
code block.

SAYTITLE <cSayTitle> is a title to assign to the SAY object.  ;
The title is not displayed on the screen but is simply a
description of the say object which is saved in the GetList.

GETTITLE <cGetTitle> is a title to assign to the GET object.  ;
The title is not displayed on the screen but is simply a
description of the get object which is saved in the GetList.

NAME <cVarName> is the variable name to assign to the GET
object (for HTML based applications.)

HYPERLINK <bHyperLink> will underline the say text and perform
an action when the say text is clicked with the mouse.

  Ex: @ 1,1 DCSAY 'http://www.donnay-software.com' ;
            COLOR GRA_CLR_BLUE ;
            SAYSIZE 0 ;
            HYPERLINK ;
             {|p,c|p := 'url.dll,FileProtocolHandler ' + ;
                        'http://www.donnay-software.com', ;
                   c := 'Rundll32.exe', ;
                   RunShell(p,c,.t.,.t.)}

CALCULATOR causes inputting into a numeric GET to function
exactly like the CalcSle() example of Xbase++.  The CalcSLE class
displays calculator-type entry fields for numeric values. The
display of entered data is right aligned, the number of decimal
places is unknown and the largest number to be entered is limited
by the width of the entry field.

SAYRESIZE <aSayResize> is an optional array of two (2) elements
used for resizing and repositioning the SAY text when the parent
is resized.

GETRESIZE <aGetResize> is an optional array of two (2) elements
used for resizing and repositioning the GET when the parent
is resized.

NOTE: SAYRESIZE and GETRESIZE are to be used in conjunction with
      the RESIZE clause of DCGETOPTIONS. See the RESIZE clause of
      DCGETOPTIONS for examples.  The optional SCALEFONT clause will
      automatically scale the font size up or down when the object
      is resized.

SAYDRAG <bSayDrag> and GETDRAG <bGetDrag> is a codeblock to evaluate
when the left mouse button is clicked in the object and the drag is
started.  The return value of the code block will be stored in memory
to be later retrieved by the Drop operation. A pointer to the clicked
on object is passed to the code block.

DIALOG <bSayDD> and <bGetDD> is a codeblock that will evaluate when
the drag is started.  This is used to call a function that will create
a dialog window which will move with the mouse during the drag.
The dialog window will be destroyed upon the drop operation
or the release of the mouse.

Ex: GETDRAG {|o|o:getData()} DIALOG {|mp1,mp2,oXbp|DragDialog(mp1,mp2,oXbp)} ;

SAYDROP <bSayDrop> and GETDROP <bGetDrop> is a codeblock to evaluate
when the left mouse button is released in the object and the drag is
ended.  A pointer to the object and the value stored in memory at the
start of the Drag are passed to the code block.

CURSOR <nSayDropCursor> and <nGetDropCurors> is the mouse cursor that
will show when it is moved over this object during a drag operation.

Ex: GETDROP {|o,x|o:setData(x),o:invalidateRect()} ;
       CURSOR CURSOR POINTER_DATADROP_ASSIGN

SAYSUBCLASS <cSaySubClass> is a string containing a class name that
will be used to create the class, rather than DC_XbpStatic().
This class should inherit from DC_XbpStatic().
See the example in \exp19\samples\subclass.

GETSUBCLASS <cGetSubClass> is a string containing a class name that
will be used to create the class, rather than DC_XbpGet().
This class should inherit from DC_XbpGet().
See the example in \exp19\samples\subclass.

FORMATTED is used to allow for displaying of formatted text with
bold, italic, underline, tabbed or indented characters.  See the
sample program in .\samples\static\formatted.prg

GETALIGN <nGetAlign> specifies how the characters are aligned within
the GET object. By default, they are left justified.
Constants defined in the XBP.CH file should be used for <nGetAlign>
The following table lists the values available for the <nGetAlign>
option:

Constants for <nAlign> :

  Constant       Description

  XBPSLE_LEFT    Text is displayed left justified

  XBPSLE_RIGHT   Text is displayed right justified

  XBPSLE_CENTER  Text is displayed centered

SAYPREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the SAY object is created.  The object is passed to
the code block.

SAYEVAL <bEval> is a code block to be evaluated by the GUI reader
after the SAY object is created.  The object is passed to the code
block.

GETPREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the GET object is created.  The object is passed to
the code block.

GETEVAL <bEval> is a code block to be evaluated by the GUI reader
after the GET object is created.  The object is passed to the code
block.

Notes:

Clauses marked by an asterisk ( * ) are not supported by DCREAD HTML or DC_ReadHtml().

------------------

GUI applications:

The SAY object created by @ DCSAY..GET is an object of the DC_XbpStatic() class unless the GRASTRING clause is used. The GRASTRING clause causes the say to be painted by the GraStringAt() function and does not create an object. DC_XbpStatic() inherits from XbpStatic()

The GET object created by @ DCSAY..GET is an object of the DC_XbpGet() class, therefore it can be manipulated with any iVar or method supported by DC_XbpGet(). DC_XbpGet() is a non-supported class which is provided with Xbase++ as an example. This class inherits from the XbpSle() class and the Get() class. It has been modified to support features required by eXPress++. The source for DC_XbpGet() is in _DCXBPGT.PRG.

If the CHECKGET option of GETOPTIONS is used, then the GET object is an object of the DC_XbpCheckBox() class.

-----------------

HTML Applications

The SAY object created by @ DCSAY..GET is an object of the DC_HtmlSay() class.

The GET object created by @ DCSAY..GET is an object of the DC_HtmlGet() class.

Examples:

/*  Example 1 (Simple Gets) */

#include "dcdialog.ch"

PROCEDURE Xtest_1()

LOCAL GetList := {}, cLastName := Space(15), cFirstName := Space(15),;
      cCompany := Space(25), cStreet := Space(25), cCity := Space(25),;
      cState := Space(2), cCountry := Space(20), cPhone := Space(15),;
      GetOptions

@ 5,10 DCSAY ' Last Name' GET cLastName
@ 5,40 DCSAY 'First Name' GET cFirstName
@ 7,10 DCSAY '   Company' GET cCompany
@ 8,10 DCSAY '    Street' GET cStreet
@ 9,10 DCSAY '      City' GET cCity
@11,10 DCSAY '     State' GET cState
@11,40 DCSAY '   Country' GET cCountry
@13,10 DCSAY '     Phone' GET cPhone PICT '(999)-999-9999'

DCGETOPTIONS SAYRIGHTJUST

DCREAD GUI ;
    FIT ;
    ADDBUTTONS ;
    OPTIONS GetOptions

RETURN

/*  Example 2 (Gets with Whens, Hides, Validations and Pop-ups)  */

PROCEDURE Xtest_2()

LOCAL GetList := {}, cLastName := Space(15), cFirstName := Space(15),;
      cCompany := Space(25), cStreet := Space(25), cCity := Space(25),;
      cState := Space(2), cCountry := Space(20), cPhone := Space(15),;
      dDate1 := Date(), dDate2 := Date()+1, GetOptions

@ 5,10 DCSAY ' Last Name' GET cLastName ;
       VALID {||DC_ReadEmpty(cLastName)}

@ 5,40 DCSAY 'First Name' GET cFirstName ;
       VALID {||DC_ReadEmpty(cFirstName)}

@ 7,10 DCSAY '   Company' GET cCompany

@ 8,10 DCSAY '    Street' GET cStreet ;
       VALID {||DC_ReadEmpty(cStreet)}

@ 9,10 DCSAY '      City' GET cCity ;
       VALID {||DC_ReadEmpty(cCity)}

@11,10 DCSAY '     State' GET cState PICT '@!' ;
       VALID {||DC_ReadEmpty(cState)} ;
       WHEN {||!Empty(cCity)}

@11,40 DCSAY '   Country' GET cCountry

@13,10 DCSAY '     Phone' GET cPhone PICT '(999)-999-9999'

@15,10 DCSAY 'Start Date' GET dDate1 ;
       POPUP {|d|DC_PopDate(d)}

@16,10 DCSAY '  End Date' GET dDate2 ;
       HIDE {||dDate1 = Date()}

DCGETOPTIONS SAYRIGHTJUST

DCREAD GUI ;
    FIT ;
    ADDBUTTONS ;
    OPTIONS GetOptions

RETURN

/* Example 3

  This example shows @ DCSAY..GETs which do direct edits into a
  database.  The GET variable is a code-block that automatically
  handles locking/unlocking and macros.  In this example, all
  screen dialog is data-driven. */

 LOCAL GetList := {}, aData, i, bBlock, bValid, bWhen

 CLOSE ALL
 USE COLLECT NEW EXCL

 aData := { { 1, 1, 'Description', 'COLLECT->descrip', '@!', ;
                    '!Empty(COLLECT->descrip)', '.T.' }, ;
            { 3, 1, 'Original Price', 'COLLECT->orig_price', '9999.99', ;
                    '.T.','.T.'}, ;
            { 5, 1, 'Date Acquired', 'COLLECT->date_acqu', '', ;
                    '.T.', '.T.' } }

 FOR i := 1 TO Len(aData)

   bBlock := _XTest3(aData[i,4],1)
   bValid := _XTest3(aData[i,6],2)
   bWhen  := _XTest3(aData[i,7],2)

   @ aData[i,1], aData[i,2] DCSAY aData[i,3] GET bBlock ;
     PICTURE aData[i,5] ;
     VALID bValid ;
     WHEN bWhen ;
     SAYRIGHT ;
     SAYSIZE 15

 NEXT

 DCREAD GUI FIT ADDBUTTONS

RETURN nil

/* -------------------- */

STATIC FUNCTION _XTest3( xValue, nMode )

IF nMode = 1 // Field Anchor
  RETURN {|x|IIF(x==nil,&xValue,IIF(dbRLock(),&xValue:=x,nil)), ;
             IIF(!(x==nil),dbUnlock(),nil),&xValue }
ENDIF

RETURN {||&xValue}  // VALID or WHEN Anchor

/* Example 4 - This example shows @ DCSAY..GET ... COMBO. */

PROCEDURE XTest_5()

LOCAL GetList := {}, cCode, aCodes, aCodeDesc

aCodes := { 'A','B','C'}

aCodeDesc := { 'Selection A', ;
               'Selection B', ;
               'Selection C' }

cCode := aCodes[1]

@ 1,1 DCSAY 'Enter Code' GET cCode GETSIZE 15 ;
      COMBO HEIGHT 6 DATA aCodeDesc RETURN {|n|aCodes[n]}

DCREAD GUI FIT ADDBUTTONS TITLE 'Combo Test'

RETURN

Files:

DCDIALOG.CH

See Also:

   @ DCSAY GET
   dc_getpopupcaption()
   @ DCGET
   dc_getcombomode()


@ DCSCROLLBAR

Create a SCROLL BAR object for displaying with GUI reader

The command @..DCSCROLLBAR creates a new Scroll-Bar object and adds the object to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> @..DCSCROLLBAR objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCSTATIC, @..DCBUTTON, @..DCCHECKBOX or @..DCTABPAGE.<br><br>

Syntax:

@ <nRow>,<nCol> DCSCROLLBAR ;
    [DATA <uVar>] ;
    [SIZE <nWidth> [,<nHeight>]] ;
    [PARENT <oParent>] ;
    [PARENTID <cParentId>] ;
    [PRESENTATION <aPres>] ;
    [TYPE <nType>] ;
    [SCROLL <bScroll>] ;
    [OBJECT <oBar>] ;
    [RANGE <nBott>,<nTop>] ;
    [TOOLTIP <bcToolTip>] ;
    [CURSOR <naCursor>] ;
    [CARGO <xCargo>] ;
    [WHEN <bWhen>] ;
    [HIDE <bHide>] ;
    [PREEVAL <bPreEval>] ;
    [EVAL <bEval>] ;
    [AUTOTRACK] ;
    [PIXEL] ;
    [RELATIVE <oRel>] ;
    [ID <cId>] ;
    [TITLE <cTitle>] ;
    [GOTFOCUS <bGotFocus>] ;
    [LOSTFOCUS <bLostFocus>]  ;
    [TABSTOP]  ;
    [NOTABSTOP];
    [TABGROUP <nTabGroup>]  ;
    [VISIBLE] ;
    [INVISIBLE] ;
    [GROUP <cGroup>] ;
    [RESIZE <aResize>] ;
    [DRAG <bDrag> [DIALOG <bDD>] ;
    [DROP <bDrop> [CURSOR <nDropCursor>] ;
    [SUBCLASS <cSubClass>]

Arguments:

<nRow> and <nCol> are the row and column of the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE <oRel> argument is
used.  If no parent is assigned, then the parent is the Dialog
box.  IF the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel mode by
including PIXEL as a command argument.

DATA <uVar> is the input/output variable. It must not be a macro
unless <uVar> is a codeblock that contains a macro. The <uVar> is
automatically anchored via a Get-Set codeblock created by
DC_GetAnchorCB() unless <uVar> is a custom Get-Set code block.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

TYPE <nType> is the type of Scrollbar.  It determines whether
a horizontal or vertical scroll bar is created.  Either the
constant XBPSCROLL_HORIZONTAL or the constant XBPSCROLL_VERTICAL
must be used for this option.  These constants are defined in
the XBP.CH file.

OBJECT <oObject> is the name of a local variable to assign
to this ScrollBar object.

SCROLL <bScroll is a code block that is evaluated when the
mouse is clicked in the scroll-bar area.  The code-block
should be in the following form:

  {| aScroll, uNIL, self | ... }

   <aScroll> := { nScrollBoxPos, nCommand }
   <aScroll> is an array containing two elements. The first
   element contains the new position of the scroll box and the
   second element contains a numeric code identifying the action
   that was executed.  Constants are defined for the actions
   that may appear in the second element.  These constants are
   defined in the XBP.CH file and are listed in the following
   table:

   XBPSB_PREVPOS      Went back one position
   XBPSB_NEXTPOS      Went forward one position
   XBPSB_PREVPAGE     Went back one page
   XBPSB_NEXTPAGE     Went forward one page
   XBPSB_SLIDERTRACK  Scroll box clicked with a mouse button
   XBPSB_ENDTRACK     Continuous scrolling using the scroll box
                      has ended

   XBPSB_ENDSCROLL    Continuous scrolling using the scroll button
                      has ended

RANGE <nMin>, <nMax> defines the minimum and maximum values of
the scroll bar.  The range is limited by the operating system
to values between -32768 and 32768.

SIZE <nWidth>,<nHeight> is the width and height of the
ScrollBar  If the PIXEL option is set to .TRUE. in DCGET
OPTIONS, then the numbers are in pixels otherwise they are
in standard text-based numbers.

AUTOTRACK causes the current position of the scroll box to be
automatically updated.   The default action is to require the
scrollbar to be updated by using the method :setData().  In
this case, the first message parameter passed to the SCROLL
code block must be used to determine the current position.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.  If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the multiline object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.

TOOLTIP <bcToolTip> is a character string which will display
as a "Tool Tip" next to the object when the cursor is passed
over the object. If <bcToolTip> is a code-block, it must return
a character string.  NOTE: The Tooltip painting method is run in
another thread, therefore the codeblock should not run code that
points to the current work area.  It may however, contain
local, public or private variables.

CURSOR <naCursor> may be either a numeric value or an array of
3 elements which defines an optional mouse pointer to use for
this object.  System mouse pointers start with
XBPWINDOW_POINTERTYPE_ and are defined in XPB.CH.  The default
pointer is XBPWINDOW_POINTERTYPE_POINTER.  <naCursor> may be a
numeric resource ID that points to a Bit-Map that has been
compiled with the resource compiler and linked to the .EXE.
<naCursor> may be a 3-element array described as follows:

  Element  Type  Description
  -------  ---- ---------------------------------------------
    [1]      C   Optional name of .DLL containing the pointer
                 resource.

    [2]      N   The numeric resource ID of the pointer.  If
                 element 1 is a NIL, then this resource must be
                 linked into the .EXE.

    [3]      N   The type of resource as defined in XBP.CH.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the object will be disabled and grayed.
If the value returned is .TRUE. then the object will be enabled.
The object is passed as a parameter to the code block.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.
The object is passed as a parameter to the code block.

GOTFOCUS <bGotFocus> is a code block that is evaluated when this
object receives input focus.  <bGotFocus> := {|uNIL1,uNIL2,self|...}

LOSTFOCUS <bLostFocus> is a code block that is evaluated when this
object loses input focus.  <bLostFocus> := {|uNIL1,uNIL2,self|...}

TABSTOP will cause the object (Xbase Part) to be set when using
the Tab key.  Note: When logical groups are defined in a dialog
using TABGROUP <nTabGroup>, TABSTOP is usually set to .T. (true)
for the first dialog element in the group.  This allows the first
dialog element of a group to be activated using the Tab key.

NOTABSTOP will cause the object (Xbase Part) to be ignored when
using the Tab key. This clause is needed only to override any
default setting of TabStop by the DCGETOPTIONS [TABSTOP] command.

TABGROUP <nTabGroup> allows objects (Xbase Parts) that are created
immediately after one another in the GetList to be combined into
logical groups. This allows the user to navigate within a dialog
from group to group by pressing the Tab key.  Within a group of
dialog elements navigation is performed using the cursor keys.

Only constants defined in the XBP.CH file can be used as values
for this instance variable.  The following table lists the
available constants:

#define constants for <nTabGroup>:

 Constant             Description

 XBP_NO_GROUP     *)  Dialog element does not belong to a group
 XBP_BEGIN_GROUP      Dialog element is the first in a group
                      (this begins the definition of the group)
 XBP_WITHIN_GROUP     Dialog element is within a group
 XBP_END_GROUP        Dialog element is the last in a group
                      (this ends the definition of the group)

*) Default value

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS

RESIZE <aResize> is an optional array of two (2) elements
used for resizing and repositioning the object when the parent
is resized.

NOTE: RESIZE is to be used in conjunction with the RESIZE clause
      of DCGETOPTIONS. See the RESIZE clause of DCGETOPTIONS for
      examples.

DRAG <bDrag> is a codeblock to evaluate when the left mouse button
is clicked in the object and the drag is started.  The return
value of the code block will be stored in memory to be later
retrieved by the Drop operation. A pointer to the clicked on
object is passed to the code block.

DIALOG <bDD> is a codeblock that will evaluate when the drag is
started.  This is used to call a function that will create a
dialog window which will move with the mouse during the drag.
The dialog window will be destroyed upon the drop operation
or the release of the mouse.

Ex: DRAG {|o|o:getData()} DIALOG {|mp1,mp2,oXbp|DragDialog(mp1,mp2,oXbp)} ;

DROP <bDrop> is a codeblock to evaluate when the left mouse button
is released in the object and the drag is ended.  A pointer to
the object and the value stored in memory at the start of the
Drag are passed to the code block.

CURSOR <nDropCursor> is the mouse cursor that will show when it
is moved over this object during a drag operation.

Ex: DROP {|o,x|o:setData(x),o:invalidateRect()} ;
       CURSOR CURSOR POINTER_DATADROP_ASSIGN

SUBCLASS <cSubClass> is a string containing a class name that
will be used to create the class, rather than DC_XbpScrollBar().
This class should inherit from DC_XbpScrollBar().
See the example in \exp19\samples\subclass.

Notes:

The object created by @ DCSCROLLBAR is an object of the XbpScrollBar() class, therefore it can be manipulated with any iVar or method supported by XbpScrollBar().

Examples:

 /*
 This example uses three scrollbars to change the RED, GREEN
 and BLUE colors and display the result in a box.
 */

 #include "dcdialog.ch"

 PROCEDURE Xtest()

 LOCAL nRed := 50, nGreen := 100, nBlue := 150, GetList := {}, oColorBox

 @ 2, 44 DCSAY 'R' SAYSIZE 2
 @ 3, 43 DCSCROLLBAR DATA nRed SIZE 3,7 ;
         TYPE XBPSCROLL_VERTICAL RANGE 0,255 ;
         SCROLL { |a,x,o| nRed := a[1], ;
           o:SetData(), RGB(nRed,nGreen,nBlue,oColorBox) }

 @ 2, 48 DCSAY 'G' SAYSIZE 2
 @ 3, 47 DCSCROLLBAR DATA nGreen SIZE 3,7 ;
         TYPE XBPSCROLL_VERTICAL RANGE 0,255 ;
         SCROLL { |a,x,o| nGreen := a[1], ;
           o:SetData(), RGB(nRed,nGreen,nBlue,oColorBox) }

 @ 2, 52 DCSAY 'B' SAYSIZE 2
 @ 3, 51 DCSCROLLBAR DATA nBlue  SIZE 3,7 ;
         TYPE XBPSCROLL_VERTICAL RANGE 0,255 ;
         SCROLL { |a,x,o| nBlue := a[1], ;
           o:SetData(), RGB(nRed,nGreen,nBlue,oColorBox) }

 @ 11, 40 DCSTATIC XBPSTATIC_TYPE_RAISEDBOX SIZE 20,2 ;
         GROUP oColorBox ;
         EVAL {|o|o:paint := {||RGB(nRed,nGreen,nBlue,oColorBox)} }

 DCREAD GUI ;
   TITLE 'Scroll-bar Demo' ;
   FIT ;
   ADDBUTTONS

 RETURN

 /* ---------------- */

 STATIC PROCEDURE RGB( nRed, nGreen, nBlue, oColorBox )

 LOCAL aAttr := Array(GRA_AA_COUNT)  // area attributes
 LOCAL nMax, aOldAttr, aOldRGB, oPS

 oPS   := oColorBox:LockPS()
 nMax  := oPS:maxColorIndex()  // max colors

 // Set new RGB color and draw box
 aAttr[ GRA_AA_COLOR  ] := nMax
 aOldAttr := oPS:setAttrArea( aAttr )
 aOldRGB  := oPS:setColorIndex( nMax, {nRed,nGreen,nBlue} )
 GraBox( oPS, {0,0}, {200,200}, GRA_FILL )
 oPS:setAttrArea( aOldAttr )
 oPS:setColorIndex( nMax, aOldRGB )
 oColorBox:unlockPS( oPS )

 RETURN

Files:

DCDIALOG.CH


@ DCSLE

Create a SINGLE LINE edit for displaying with GUI reader

The command @..DCSLE creates a new single-line edit definition and adds it to the array named GETLIST which is later processed by the DC_Read*() functions or by the DCREAD * commands. The GETLIST array must be first declared and initialized to the value of {}. <br><br> The command DCREAD GUI creates the DC_Xbp*() objects and activates the edit mode for all definitions found in the GetList array.<br><br> The command DCREAD HTML creates the DC_Html*() objects and writes the HTML source code.<br><br> A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> @..DCSLE objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCRADIO, @..DCBUTTON, @..DCCHECKBOX or @..DCTABPAGE.<br><br> <br><br>

Syntax:

@ <nRow>,<nCol> DCSLE <uVar> ;
    [PARENT <oParent>] ;
    [PARENTID <cParentId>] ;
    [VALID <bValid>] ;
    [WHEN <bWhen>] ;
    [HIDE <bHide>] ;
  * [EDITPROTECT <bProtect>] ;
    [SIZE <nWidth>,<nHeight>] ;
    [MESSAGE <bcMsg> [INTO <oMsgBox>]] ;
    [FONT <bocFont>] ;
    [COLOR <bncFgC> [,<ncBgC>] ] ;
    [HELPCODE <cHelpCode>] ;
  * [DATALINK <bLink>] ;
    [OBJECT <oObject>] ;
    [CARGO <xCargo>] ;
  * [PRESENTATION <aPres>] ;
  * [PIXEL] ;
  * [TOOLTIP <bcToolTip>] ;
  * [CURSOR <naCursor>] ;
    [PREEVAL <bPreEval>] ;
    [EVAL <bEval>] ;
    [RELATIVE <oRel>] ;
    [ID <cId>] ;
    [TITLE <cTitle>] ;
  * [ACCELKEY <nKey>] ;
  * [GOTFOCUS <bGotFocus>] ;
  * [LOSTFOCUS <bLostFocus>] ;
  * [TABSTOP] ;
  * [NOTABSTOP] ;
  * [TABGROUP <nTabGroup>] ;
  * [VISIBLE] ;
  * [INVISIBLE] ;
    [GROUP <cGroup>] ;
    [NAME <cVarName>] ;
    [RESIZE <aResize> [SCALEFONT] ] ;
    [DRAG <bDrag> [DIALOG <bDD>] ;
    [DROP <bDrop> [CURSOR <nDropCursor>] ;
    [SUBCLASS <cSubClass>] ;
    [BUFFERLENGTH <nBufferLen>] ;
    [ALIGN <nAlign>] ;
    [CUEBANNER <cCueBanner>]

Arguments:

GUI applications:

<nRow> and <nCol> are the row and column of the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE <oRel> argument is
used.  If no parent is assigned, then the parent is the Dialog
box.  IF the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel
mode by including PIXEL as a command argument.

HTML applications:

<nRow> and <nCol> are the row number and column number of
the table if the parent of this object is a DCTABLE. The
text will be inserted in the cell of the table defined by
the row/column.

<uVar> is the input/output variable.  This should be
initialized to a character string. It must not be a macro, however
it may be a code block that contains a macro. The <uVar> is
automatically anchored via a Get-Set codeblock created by
DC_GetAnchorCB() unless <uVar> is a custom Get-Set
code block.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

SIZE <nWidth>,<nHeight> is the width and height of the
multiline box.  If the PIXEL option is set to .TRUE. in DCGET
OPTIONS, then the numbers are in pixels otherwise they are
in standard text-based numbers.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.  If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

OBJECT <oObject> is the name of the variable to assign as a
storage place for this object.

FONT <cFont> is a character string defining an optional font.
The font string must conform to the Xbase++ standard, ie.
"10.Courier Bold". It may also be a font object or a code block
that returns a character string or a font object to later
refresh with DC_GetRefresh().

MESSAGE <bcMsg> is the message you want to display in the
message area of the dialogue screen defined by the DCMESSAGEBOX
command when the object is in focus.  Optionally, INTO <oMsgBox>
will designate which message box to display the message into.
If the INTO clause is not used, then the last message box in the
GetList is the default. <oMsgBox> may also be any object that
supports the :setCaption() method.If <bcMsg> is a code-block,
it must return a character string.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the object will be disabled and grayed.
If the value returned is .TRUE. then the object will be enabled.
The object is passed as a parameter to the code block.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.
The object is passed as a parameter to the code block.

EDITPROTECT <bProtect> is an optional condition tested during the
execution of the GUI gets by the DCREAD GUI command, before the
object receives input focus (before it is activated). When the
condition returns the value .T. (true), the object receives the
input focus.  Otherwise, it is skipped. <bProtect> is a code
block that must return a logical value when evaluated. The code
block is evaluated prior to the object receiving input focus.
This clause behaves similar to the WHEN clause with the exception
that the object is not disabled (grayed out).  The object is
passed as a parameter to the code block.

VALID <bValid> is an optional condition tested during the
execution of the GUI gets by the READ command before an
object loses input focus (before it is deactivated).  When
the condition returns the value .T. (true), the object
loses the input focus.  Otherwise, it remains active. <bValid>
is a code block that must return a logical value when it is
evaluated.  The object passed as a parameter to the code block.

HELPCODE <cHelp> is a character string that is passed to the
DC_HelpF1() function if F1 is pressed or the HELP button
is clicked when this object has focus.  This HELPCODE allows
the Help system to override the passing of the Procedure and
Varname for more specific context-help.

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the multiline object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.

TOOLTIP <bcToolTip> is a character string which will display
as a "Tool Tip" next to the object when the cursor is passed
over the object. A semi-colon within the text indicates a new
line.  If <bcToolTip> is a code-block, it must return a character
string.  NOTE: The Tooltip painting method is run in another
thread, therefore the codeblock should not run code that points
to the current work area.  It may however, contain local, public
or private variables.

CURSOR <naCursor> may be either a numeric value or an array of
3 elements which defines an optional mouse pointer to use for
this object.  System mouse pointers start with
XBPWINDOW_POINTERTYPE_ and are defined in XPB.CH.  The default
pointer is XBPWINDOW_POINTERTYPE_POINTER.  <naCursor> may be a
numeric resource ID that points to a Bit-Map that has been
compiled with the resource compiler and linked to the .EXE.
<naCursor> may be a 3-element array described as follows:

  Element  Type  Description
  -------  ---- ---------------------------------------------
    [1]      C   Optional name of .DLL containing the pointer
                 resource.

    [2]      N   The numeric resource ID of the pointer.  If
                 element 1 is a NIL, then this resource must be
                 linked into the .EXE.

    [3]      N   The type of resource as defined in XBP.CH.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

COLOR <ncFGc>, <ncBGc> are foreground and background colors.
They may be character strings representing valid text-based
colors supported by SetColor() or they may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH. If <bncFGc> is a
code block is must return a 2-element array containing a
foreground and background color.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

DATALINK <bLink> is an optional code block that is evaluated
every time Get/Set codeblock is evaluated, ie when the data
is read from the <uVar> into the object except when using
a user-defined Get/Set code block.  <bLink> is also
evaluated when DC_GetRefresh() is called unless the <lDataLink>
parameter of DC_GetRefresh() is .FALSE.

ACCELKEY <nKey> is a numeric "hot-key" assignment that will set
focus to the memo object when the hot-key is pressed.  The key
must be a valid key with the prefix xbeK_*.  These keys are
defined in APPEVENT.CH.

GOTFOCUS <bGotFocus> is a code block that is evaluated when this
object receives input focus.  <bGotFocus> := {|uNIL1,uNIL2,self|...}

LOSTFOCUS <bLostFocus> is a code block that is evaluated when this
object loses input focus.  <bLostFocus> := {|uNIL1,uNIL2,self|...}

TABSTOP will cause the object (Xbase Part) to be set when using
the Tab key.  Note: When logical groups are defined in a dialog
using TABGROUP <nTabGroup>, TABSTOP is usually set to .T. (true)
for the first dialog element in the group.  This allows the first
dialog element of a group to be activated using the Tab key.

NOTABSTOP will cause the object (Xbase Part) to be ignored when
using the Tab key. This clause is needed only to override any
default setting of TabStop by the DCGETOPTIONS [TABSTOP] command.

TABGROUP <nTabGroup> allows objects (Xbase Parts) that are created
immediately after one another in the GetList to be combined into
logical groups. This allows the user to navigate within a dialog
from group to group by pressing the Tab key.  Within a group of
dialog elements navigation is performed using the cursor keys.

Only constants defined in the XBP.CH file can be used as values
for this instance variable.  The following table lists the
available constants:

#define constants for <nTabGroup>:

 Constant             Description

 XBP_NO_GROUP     *)  Dialog element does not belong to a group
 XBP_BEGIN_GROUP      Dialog element is the first in a group
                      (this begins the definition of the group)
 XBP_WITHIN_GROUP     Dialog element is within a group
 XBP_END_GROUP        Dialog element is the last in a group
                      (this ends the definition of the group)

*) Default value

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().
VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS.

NAME <cVarName> is the variable name to assign to the GET
object (for HTML based applications.)

RESIZE <aResize> is an optional array of two (2) elements
used for resizing and repositioning the object when the parent
is resized.

NOTE: RESIZE is to be used in conjunction with the RESIZE clause
      of DCGETOPTIONS. See the RESIZE clause of DCGETOPTIONS for
      examples.

      The optional SCALEFONT clause will automatically scale the
      font size up or down when the object is resized.

DRAG <bDrag> is a codeblock to evaluate when the left mouse button
is clicked in the object and the drag is started.  The return
value of the code block will be stored in memory to be later
retrieved by the Drop operation. A pointer to the clicked on
object is passed to the code block.

DIALOG <bDD> is a codeblock that will evaluate when the drag is
started.  This is used to call a function that will create a
dialog window which will move with the mouse during the drag.
The dialog window will be destroyed upon the drop operation
or the release of the mouse.

Ex: DRAG {|o|o:getData()} DIALOG {|mp1,mp2,oXbp|DragDialog(mp1,mp2,oXbp)} ;

DROP <bDrop> is a codeblock to evaluate when the left mouse button
is released in the object and the drag is ended.  A pointer to
the object and the value stored in memory at the start of the
Drag are passed to the code block.

CURSOR <nDropCursor> is the mouse cursor that will show when it
is moved over this object during a drag operation.

Ex: DROP {|o,x|o:setData(x),o:invalidateRect()} ;
       CURSOR CURSOR POINTER_DATADROP_ASSIGN

SUBCLASS <cSubClass> is a string containing a class name that
will be used to create the class, rather than DC_XbpSle().
This class should inherit from DC_XbpSle().
See the example in \exp19\samples\subclass.

BUFFERLENGTH <nBufferLen> sets the maximum length of the buffer
that is created when characters are entered into the control.
The default is 32.

ALIGN <nAlign> specifies how the characters are aligned within
the XbpSLE object. By default, they are left justified.
Constants defined in the XBP.CH file should be used for <nAlign>
The following table lists the values available for the <nAlign>
option:

Constants for <nAlign> :

  Constant       Description

  XBPSLE_LEFT    Text is displayed left justified

  XBPSLE_RIGHT   Text is displayed right justified

  XBPSLE_CENTER  Text is displayed centered

CUEBANNER <cCueBanner> is the cue banner to display when the
object text is empty.

Notes:

Clauses marked by an asterisk ( * ) are not supported by DCREAD HTML or DC_ReadHtml().

------------------

GUI applications:

The sle object created by @ DCDIALOG is an object of the DC_XbpSLE() class which inherits from the XbpSle() class, therefore it can be manipulated with any iVar or method supported by XbpSLE().

------------------

HTML applications:

The multiline object created by @ DCDIALOG is an object of the DC_HtmlSLE() class.

Files:

DCDIALOG.CH

See Also:

   @ DCGET
   @ DCMULTILINE


@ DCSPINBUTTON

Create a SPIN BUTTON get for displaying with GUI reader

The command @..DCSPINBUTTON creates a new SpinButton edit object and adds the object to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> @..DCSPINBUTTON objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCRADIO, @..DCPUSHBUTTON, @..DCCHECKBOX or @..DCTABPAGE.<br><br>

Syntax:

@ <nRow>,<nCol> DCSPINBUTTON <nVar> ;
    [SIZE <nWidth> [,<nHeight>]] ;
    [PARENT <oParent>] ;
    [PARENTID <cParentId>] ;
    [MESSAGE <bcMsg> [INTO <oMsgBox>]] ;
    [VALID <bValid>] ;
    [HELPCODE <cHelp>] ;
    [WHEN <bWhen>] ;
    [HIDE <bHide>] ;
    [EDITPROTECT <bProtect>] ;
    [PRESENTATION <aPres>] ;
    [FONT <bocFont>] ;
    [MASTER <oMaster>] ;
    [OBJECT <oObject>] ;
    [CALLBACK <bCallBack>] ;
    [COLOR <bncFgC> [,<ncBgC>] ] ;
    [DATALINK <bLink>] ;
    [LIMITS <nBott>,<nTop>] ;
    [PIXEL] ;
    [FASTSPIN] ;
    [PADZERO] ;
    [TOOLTIP <bcToolTip>] ;
    [CURSOR <naCursor>] ;
    [CARGO <xCargo>] ;
    [PREEVAL <bPreEval>] ;
    [EVAL <bEval>] ;
    [RELATIVE <oRel>] ;
    [ID <cId>] ;
    [TITLE <cTitle>] ;
    [ACCELKEY <anAccel>] ;
    [GOTFOCUS <bGotFocus>] ;
    [LOSTFOCUS <bLostFocus>] ;
    [TABSTOP] ;
    [NOTABSTOP] ;
    [TABGROUP <nTabGroup>] ;
    [VISIBLE] ;
    [INVISIBLE] ;
    [GROUP <cGroup>] ;
    [RESIZE <aResize> [SCALEFONT] ] ;
    [ENDSPIN <bEndSpin>] ;
    [DOWNSPIN <bDownSpin>] ;
    [UPSPIN <bUpSpin>] ;
    [DRAG <bDrag> [DIALOG <bDD>] ;
    [DROP <bDrop> [CURSOR <nDropCursor>] ;
    [SUBCLASS <cSubClass>] ;
    [INCREMENT <nIncrement>]

Arguments:

<nRow> and <nCol> are the row and column of the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE <oRel> argument is
used.  If no parent is assigned, then the parent is the Dialog
box.  IF the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel
mode by including PIXEL as a command argument.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

MASTER <oMaster> is a variable containing another spin button
object that will be used as the master for this spin button.
In this case, the spinbutton is displayed without the two
pushbutton arrows.  Instead the value of the spinbutton is
changed when one of the arrows on the master spinbutton is
clicked.

OBJECT <oObject> is the name of a local variable to assign
to this spinbutton object.

CALLBACK <bCallBack> is a code block that is evaluated
when the end-spin is encountered or when a keyboard entry is
made into the spinbutton text area.

LIMITS <nBott>,<nTop> defines the valid range for numeric
values of the spinbutton.  If the current value of the
spinbutton is outside the newly defined range when this
object is created, the value is set to the minimum or maximum
valid value depending on whether the invalid value is less
than the minimum or greater than the maximum valid value.

In the default mode, changes to the value are somewhat slower
when the mouse button is clicked on one of the arrows and the
button remains pressed.  In the FASTSPIN mode, the spinbutton
is in the "fast" operation. mode.   The value is incremented
or decremented at twice the normal speed.  If the spinbutton is
defined as the master for another spinbutton, the FASTSPIN
option is ignored.

By default, the numeric value in the entry field is displayed
without leading zeros.  Use PADZERO to cause the display to
contain leading zeros.

<nVar> is the input/output variable.  This should be
initialized to a numeric value.  It must not be a macro unless
<nVar> is a codeblock that contains a macro. The <nVar> is
automatically anchored via a Get-Set codeblock created by
DC_GetAnchorCB() unless <lVar> is a custom Get-Set code block.

SIZE <nWidth>,<nHeight> is the width and height of the
spin button.  If the PIXEL option is set to .TRUE. in DCGET
OPTIONS, then the numbers are in pixels otherwise they are
in standard text-based numbers.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object. If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

FONT <bocFont> is a character string defining an optional font.
The font string must conform to the Xbase++ standard, ie.
"10.Courier Bold".  It may also be a font object or a code block
that returns a character string or a font object to later
refresh with DC_GetRefresh().

MESSAGE <bcMsg> is the message you want to display in the
message area of the dialogue screen defined by the DCMESSAGEBOX
command when the object is in focus.  Optionally, INTO <oMsgBox>
will designate which message box to display the message into.
If the INTO clause is not used, then the last message box in the
GetList is the default. <oMsgBox> may also be any object that
supports the :setCaption() method.  If <bcMsg> is a code-block,
it must return a character string.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the object will be disabled and grayed.
If the value returned is .TRUE. then the object will be enabled.
The object is passed as a parameter to the code block.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.
The object is passed as a parameter to the code block.

EDITPROTECT <bProtect> is an optional condition tested during the
execution of the GUI gets by the DCREAD GUI command, before the
object receives input focus (before it is activated). When the
condition returns the value .T. (true), the object receives the
input focus.  Otherwise, it is skipped. <bProtect> is a code
block that must return a logical value when evaluated. The code
block is evaluated prior to the object receiving input focus.
This clause behaves similar to the WHEN clause with the exception
that the object is not disabled (grayed out).  The object is
passed as a parameter to the code block.

VALID <bValid> is an optional condition tested during the
execution of the GUI gets by the READ command before an
object loses input focus (before it is deactivated).  When
the condition returns the value .T. (true), the object
loses the input focus.  Otherwise, it remains active. <bValid>
is a code block that must return a logical value when it is
evaluated.  The object passed as a parameter to the code block.

HELPCODE <cHelp> is a character string that is passed to the
DC_HelpF1() function if F1 is pressed or the HELP button
is clicked when this object has focus.  This HELPCODE allows
the Help system to override the passing of the Procedure and
Varname for more specific context-help.

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the spinbutton object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.

TOOLTIP <bcToolTip> is a character string which will display
as a "Tool Tip" next to the object when the cursor is passed
over the object. A semi-colon within the text indicates a new
line.  If <bcToolTip> is a code-block, it must return a character
string.  NOTE: The Tooltip painting method is run in another
thread, therefore the codeblock should not run code that points
to the current work area.  It may however, contain local, public
or private variables.

CURSOR <naCursor> may be either a numeric value or an array of
3 elements which defines an optional mouse pointer to use for
this object.  System mouse pointers start with
XBPWINDOW_POINTERTYPE_ and are defined in XPB.CH.  The default
pointer is XBPWINDOW_POINTERTYPE_POINTER.  <naCursor> may be a
numeric resource ID that points to a Bit-Map that has been
compiled with the resource compiler and linked to the .EXE.
<naCursor> may be a 3-element array described as follows:

  Element  Type  Description
  -------  ---- ---------------------------------------------
    [1]      C   Optional name of .DLL containing the pointer
                 resource.

    [2]      N   The numeric resource ID of the pointer.  If
                 element 1 is a NIL, then this resource must be
                 linked into the .EXE.

    [3]      N   The type of resource as defined in XBP.CH.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

COLOR <ncFGc>, <ncBGc> are foreground and background colors.
They may be character strings representing valid text-based
colors supported by SetColor() or they may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH. If <bncFGc> is a
code block is must return a 2-element array containing a
foreground and background color.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

ACCELKEY <anAccel> is a numeric "hot-key" assignment that will set
focus to the checkbox object when the hot-key is pressed.  The key
must be a valid key with the prefix xbeK_*.  These keys are
defined in APPEVENT.CH.  <anAccel> may also be an array of numeric
values to assign more than one key to the object.

GOTFOCUS <bGotFocus> is a code block that is evaluated when this
object receives input focus.  <bGotFocus> := {|uNIL1,uNIL2,self|...}

LOSTFOCUS <bLostFocus> is a code block that is evaluated when this
object loses input focus.  <bLostFocus> := {|uNIL1,uNIL2,self|...}

TABSTOP will cause the object (Xbase Part) to be set when using
the Tab key.  Note: When logical groups are defined in a dialog
using TABGROUP <nTabGroup>, TABSTOP is usually set to .T. (true)
for the first dialog element in the group.  This allows the first
dialog element of a group to be activated using the Tab key.

NOTABSTOP will cause the object (Xbase Part) to be ignored when
using the Tab key. This clause is needed only to override any
default setting of TabStop by the DCGETOPTIONS [TABSTOP] command.

TABGROUP <nTabGroup> allows objects (Xbase Parts) that are created
immediately after one another in the GetList to be combined into
logical groups. This allows the user to navigate within a dialog
from group to group by pressing the Tab key.  Within a group of
dialog elements navigation is performed using the cursor keys.

Only constants defined in the XBP.CH file can be used as values
for this instance variable.  The following table lists the
available constants:

#define constants for <nTabGroup>:

 Constant             Description

 XBP_NO_GROUP     *)  Dialog element does not belong to a group
 XBP_BEGIN_GROUP      Dialog element is the first in a group
                      (this begins the definition of the group)
 XBP_WITHIN_GROUP     Dialog element is within a group
 XBP_END_GROUP        Dialog element is the last in a group
                      (this ends the definition of the group)

*) Default value

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS.

DATALINK <bLink> is an optional code block that is evaluated
every time Get/Set codeblock is evaluated, ie when the data
is read from the <uVar> into the object except when using
a user-defined Get/Set code block.

RESIZE <aResize> is an optional array of two (2) elements
used for resizing and repositioning the object when the parent
is resized.

NOTE: RESIZE is to be used in conjunction with the RESIZE clause
      of DCGETOPTIONS. See the RESIZE clause of DCGETOPTIONS for
      examples.

      The optional SCALEFONT clause will automatically scale the
      font size up or down when the object is resized.

ENDSPIN <bEndSpin> is a code block to evaluate when the left
mouse button is released after pressing the up or down pushbutton
of the SpinButton object.

DOWNSPIN <bDownSpin> is a code block to evaluate after the numeric
value in the entry field of the Spinbutton object is decremented.
This occurs either after the user presses the Down Arrow key or
clicks the down pushbutton with the mouse.

UPSPIN <bUpSpin> is a code block to evaluate after the numeric
value in the entry field of the XbpSpinbutton object is incremented.
This occurs when the user presses the Up arrow key or presses
the up pushbutton of the spinbutton with the mouse.

DRAG <bDrag> is a codeblock to evaluate when the left mouse button
is clicked in the object and the drag is started.  The return
value of the code block will be stored in memory to be later
retrieved by the Drop operation. A pointer to the clicked on
object is passed to the code block.

DIALOG <bDD> is a codeblock that will evaluate when the drag is
started.  This is used to call a function that will create a
dialog window which will move with the mouse during the drag.
The dialog window will be destroyed upon the drop operation
or the release of the mouse.

Ex: DRAG {|o|o:getData()} DIALOG {|mp1,mp2,oXbp|DragDialog(mp1,mp2,oXbp)} ;

DROP <bDrop> is a codeblock to evaluate when the left mouse button
is released in the object and the drag is ended.  A pointer to
the object and the value stored in memory at the start of the
Drag are passed to the code block.

CURSOR <nDropCursor> is the mouse cursor that will show when it
is moved over this object during a drag operation.

Ex: DROP {|o,x|o:setData(x),o:invalidateRect()} ;
       CURSOR CURSOR POINTER_DATADROP_ASSIGN

SUBCLASS <cSubClass> is a string containing a class name that
will be used to create the class, rather than DC_XbpSpinButton().
This class should inherit from DC_XbpSpinButton().
See the example in \exp19\samples\subclass.

INCREMENT <nIncrement> is a numeric value that sets the amount of
increment or decrement for each navigation.

Notes:

The object created by @ DCSPINBUTTON is an object of the XbpSpinButton() class, therefore it can be manipulated with any iVar or method supported by XbpSpinButton().

Examples:

 #include "dcdialog.ch"
 #include "gra.ch"

 #define nRed        aLocals[1]
 #define nGreen      aLocals[2]
 #define nBlue       aLocals[3]
 #define oRedSpin    aLocals[4]
 #define oGreenSpin  aLocals[5]
 #define oBlueSpin   aLocals[6]
 #define oColorBox   aLocals[7]
 #define oPS         aLocals[8]

 PROCEDURE Xtest()

 LOCAL aLocals[8], GetList := {}

 nRed   := 50 ; nGreen := 100 ; nBlue  := 150

 @ 2, 57 DCSPINBUTTON nRed SIZE 7 LIMITS 0,255 ;
         OBJECT oRedSpin ;
         CALLBACK {|a,b,o|o:GetData(),RGB(aLocals)}
 @ 0, 8  DCSAY 'Red' SAYSIZE 5 RELATIVE oRedSpin

 @ 4, 57 DCSPINBUTTON nGreen SIZE 7 LIMITS 0,255 ;
         OBJECT oGreenSpin ;
         CALLBACK {|a,b,o|o:GetData(),RGB(aLocals)}
 @ 0, 8  DCSAY 'Green' SAYSIZE 5 RELATIVE oGreenSpin

 @ 6, 57 DCSPINBUTTON nBlue SIZE 7 LIMITS 0,255 ;
         OBJECT oBlueSpin ;
         CALLBACK {|a,b,o|o:GetData(),RGB(aLocals)}
 @ 0, 8  DCSAY 'Blue' SAYSIZE 5 RELATIVE oBlueSpin

 @ 8, 56 DCSTATIC XBPSTATIC_TYPE_RAISEDBOX SIZE 10,2 ;
         GROUP oColorBox EVAL {|o|o:paint := {||RGB(aLocals)} }

 DCREAD GUI ;
   TITLE 'Spin-Button Demo' ;
   FIT ;
   ADDBUTTONS

 RETURN

 /* ------------------- */

 STATIC PROCEDURE RGB( aLocals )

 LOCAL aAttr := Array(GRA_AA_COUNT)
 LOCAL nMax, aOldAttr, aOldRGB

 oPS   := oColorBox:LockPS()
 nMax  := oPS:maxColorIndex()  // max colors

 // Set new RGB color and draw box
 aAttr[ GRA_AA_COLOR  ] := nMax
 aOldAttr := oPS:setAttrArea( aAttr )
 aOldRGB  := oPS:setColorIndex( nMax, {nRed,nGreen,nBlue} )
 GraBox( oPS, {0,0}, {100,100}, GRA_FILL )
 oPS:setAttrArea( aOldAttr )
 oPS:setColorIndex( nMax, aOldRGB )
 oColorBox:unlockPS( oPS )

 RETURN

Files:

DCDIALOG.CH


@ DCSPLITBAR

Create a SPLITBAR object for displaying with GUI reader

The command @..DCSPLITBAR creates a new SplitBar object and adds the object to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> @..DCSPLITBAR objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCSTATIC, @..DCBUTTON, @..DCCHECKBOX or @..DCTABPAGE.<br><br> @ DCSPLITBAR is used to create a vertical or horizontal bar to be used for proportionally resizing adjacent screen objects. <br><br>

Syntax:

@ <nRow>, <nCol> DCSPLITBAR <oSplitBar>                            ;
                [SIZE <nWidth>,<nHeight>]                                   ;
                [PARENT <oParent>]                                          ;
                [PARENTID <cPID>]                                           ;
                [PRESENTATION <aPres>]                                      ;
                [COLOR <ncBgC>]                                             ;
                [MOVECOLOR <nMoveColor>]                                    ;
                [CARGO <xCargo>]                                            ;
                [ORIENTATION <nOrientation>]                                ;
                [TITLE <cTitle>]                                            ;
                [EVAL <bEval>]                                              ;
                [PREEVAL <bPreEval>]                                        ;
                [POSTEVAL <bPostEval>]                                      ;
                [CURSOR <nCursor>]                                          ;
                [ID <cId>]
                [PIXEL] ;                                                ;
                [GROUP <cGroup>]                                            ;
                [CLASS <bcClass>]                                ;
                [PREDECESSOR <oPredecessor>]                                ;
                [SUCCESSOR <oSuccessor>]                                    ;
                [MINSIZE <nMinSize>]                                        ;
                [MAXSIZE <nMaxSize>]
                [RESIZE <aReSize>]                                          ;
                [SUBCLASS <cSubClass>]

Arguments:

<nRow> and <nCol> are the row and column of the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE <oRel> argument is
used.  If no parent is assigned, then the parent is the Dialog
box.  IF the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel mode by
including PIXEL as a command argument.

<oSplitBar> is the name of a local variable to assign
to this SplitBar object.

SIZE <nWidth>,<nHeight> is the width and height of the
ScrollBar  If the PIXEL option is set to .TRUE. in DCGET
OPTIONS, then the numbers are in pixels otherwise they are
in standard text-based numbers.

COLOR <ncBgC> is the color of the SplitBar.

ORIENTATION <nOrientation> is the orientation (Horizontal or
Vertical) of the SplitBar.  Values may be DCGUI_SPLITBAR_VERTICAL
or DCGUI_SPLITBAR_HORIZONTAL.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.  If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

TOOLTIP <bcToolTip> is a character string which will display
as a "Tool Tip" next to the object when the cursor is passed
over the object. If <bcToolTip> is a code-block, it must return
a character string.  NOTE: The Tooltip painting method is run in
another thread, therefore the codeblock should not run code that
points to the current work area.  It may however, contain
local, public or private variables.

CURSOR <naCursor> may be either a numeric value or an array of
3 elements which defines an optional mouse pointer to use for
this object.  System mouse pointers start with
XBPWINDOW_POINTERTYPE_ and are defined in XPB.CH.  The default
pointer is XBPWINDOW_POINTERTYPE_POINTER.  <naCursor> may be a
numeric resource ID that points to a Bit-Map that has been
compiled with the resource compiler and linked to the .EXE.
<naCursor> may be a 3-element array described as follows:

  Element  Type  Description
  -------  ---- ---------------------------------------------
    [1]      C   Optional name of .DLL containing the pointer
                 resource.

    [2]      N   The numeric resource ID of the pointer.  If
                 element 1 is a NIL, then this resource must be
                 linked into the .EXE.

    [3]      N   The type of resource as defined in XBP.CH.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS

RESIZE <aResize> is an optional array of two (2) elements
used for resizing and repositioning the object when the parent
is resized.

NOTE: RESIZE is to be used in conjunction with the RESIZE clause
      of DCGETOPTIONS. See the RESIZE clause of DCGETOPTIONS for
      examples.

PREDECESSOR <oPredecessor> is the predecessor object that will
be resized when the SplitBar is moved. If the SplitBar orientation
is Vertical then this is the left-most object.  If the SplitBar
orientation is Horizontal then this is the bottom-most object.

SUCCESSOR <oSuccessor> is the successor object that will
be resized when the SplitBar is moved. If the SplitBar orientation
is Vertical then this is the right-most object. If the SplitBar
orientation is Horizontal then this is the top-most object.

MINSIZE nMinSize is the minimum size, in pixels, of the predecessor
object.

MAXSIZE nMaxSize is the maximum size, in pixels, of the predecessor
object.

SUBCLASS <cSubClass> is a string containing a class name that
will be used to create the class, rather than DC_XbpSplitBar().
This class should inherit from DC_XbpSplitBar().
See the example in \exp19\samples\subclass.

Notes:

The object created by @ DCSPLITBAR is an object of the XbpStatic() class, therefore it can be manipulated with any iVar or method supported by XbpStatic().

Examples:

 Look at the sample program in the .\SAMPLES\SPLITBAR directory.

Files:

DCDIALOG.CH


@ DCSTATIC

Create a STATIC object for displaying with GUI reader

The command @..DCSTATIC creates a new Static object and adds the object to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> @..DCSTATIC objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCRADIO, @..DCPUSHBUTTON or @..DCMULTILINE.<br><br>

Syntax:

@ <nRow>,<nCol> DCSTATIC ;
    TYPE <nType> ;
    [SIZE <nWidth>, <nHeight>] ;
    [OBJECT <oObject>] ;
    [PARENT <oParent>] ;
    [PARENTID <cParentId>] ;
    [COLOR <bncFgC> [,<ncBgC>] ] ;
    [OPTIONS <nOptions>] ;
    [CARGO <xCargo>] ;
    [HIDE <bHide>] ;
    [CAPTION <ncboCaption>] ;
    [PRESENTATION <aPres>] ;
    [PIXEL] ;
    [FONT <bocFont>] ;
    [TOOLTIP <bcToolTip>] ;
    [CURSOR <naCursor>] ;
    [PREEVAL <bPreEval>] ;
    [EVAL <bEval>] ;
    [RELATIVE <oRel>] ;
    [ID <cId>] ;
    [TITLE <cTitle>] ;
    [TABSTOP]  ;
    [NOTABSTOP];
    [TABGROUP <nTabGroup>] ;
    [VISIBLE] ;
    [INVISIBLE] ;
    [GROUP <cGroup>] ;
    [VSCROLL <oParentV> RANGE <nVStart>, <nVEnd> ;
        [OBJECT <oObjectV> ] ] ;
    [HSCROLL <oParentH> RANGE <nHStart>, <nHEnd> ;
        [OBJECT <oObjectH> ] ] ;
    [RESIZE <aResize> [SCALEFONT] ] ;
    [RESTYPE <cResType>] ;
    [RESFILE <cResFile>] ;
    [DRAG <bDrag> [DIALOG <bDD>] ;
    [DROP <bDrop> [CURSOR <nDropCursor>] ;
    [SUBCLASS <cSubClass>] ;
    [FORMATTED]

Arguments:

<nRow>, <nCol> are the coordinates on the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE <oRel> argument is
used.  If no parent is assigned, then the parent is the Dialog
box.  IF the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel
mode by including PIXEL as a command argument.

<nType> defines the "type" of the static object.  Static
objects can be anything supported by the XbpStatic()
class - Text, Icons, BitMaps, Boxes, etc.  <nType> must be
a constant starting with XBPSTATIC_TYPE_.  These constants
are defined in XBP.CH.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

SIZE <nWidth>, <nHeight> defines the size of the object.
If no size is given, then the object will be automatically
sized to fit the caption.  IF the PIXEL option is set to .TRUE.
in DCGETOPTIONS, then the numbers are in pixels otherwise they
are in standard text-based coordinates.  You can also force the
pixel mode by including PIXEL in the command.

CAPTION <ncbCaption> is the caption to place on the object.
The caption is the part of a DCSTATIC object that is displayed
within the area of the object.  The caption can be a character
string, a bitmap/icon resource (raster image), a bitmap object,
or a code-block which returns a character string, numeric
resource or bitmap object. If it is a character string, the
string is assigned. If the caption is a bitmap or icon, the
numeric resource ID of the bitmap or icon is assigned. If a
resource ID is used, it must be defined in a resource file that
is linked to the EXE file using the resource compiler.  If an
object is used, it must be an object of the XbpBitMap() class.
An object may be used only with Xbase++ 1.7 or later.  If
<ncboCaption> is a code-block, the caption is refreshed with the
DC_GetRefresh() function.

When the DCSTATIC object is used to display lines, borders or
boxes, the caption is not generally displayed. The single
exception is when a DCSTATIC object of the
XBPSTATIC_TYPE_GROUPBOX type is used to display a box with a
title (caption) at the upper left.

Predefined system icons:

If the type of the XbpStatic object is XBPSTATIC_TYPE_SYSICON,
the constant assigned to the caption identifies a predefined
system icon. These do not need to be defined in a resource
file and can not be linked to the EXE file using the resource
compiler.  The constants are defined in the XBP.CH file.

OBJECT <oObject> is the name of the variable to assign as a
storage place for this object.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object. If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

FONT <cFont> is a character string defining an optional font.
The font string must conform to the Xbase++ standard, ie.
"10.Courier Bold". It may also be a font object or a code block
that returns a character string or a font object to later
refresh with DC_GetRefresh().

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the Static object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.

OPTIONS <nOptions> is a set of options that can be used to
align the text within the rectangular area of the Static object.
Constants defined in the XBP.CH file are used for these options.
If combinations of alignment options are required, the sum of
the appropriate constants must be included in <nOptions>.

 XBPSTATIC_TEXT_LEFT       Text is left aligned
 XBPSTATIC_TEXT_CENTER     Text is horizontally centered
 XBPSTATIC_TEXT_RIGHT      Text is right aligned
 XBPSTATIC_TEXT_TOP        Text is displayed at top
 XBPSTATIC_TEXT_VCENTER    Text is vertically centered
 XBPSTATIC_TEXT_BOTTOM     Text is displayed at bottom
 XBPSTATIC_TEXT_WORDBREAK  Text is wrapped (multi-line)

TOOLTIP <bcToolTip> is a character string which will display
as a "Tool Tip" next to the object when the cursor is passed
over the object. A semi-colon within the text indicates a new
line.  If <bcToolTip> is a code-block, it must return a character
string.  NOTE: The Tooltip painting method is run in another
thread, therefore the codeblock should not run code that points
to the current work area.  It may however, contain local, public
or private variables.

CURSOR <naCursor> may be either a numeric value or an array of
3 elements which defines an optional mouse pointer to use for
this object.  System mouse pointers start with
XBPWINDOW_POINTERTYPE_ and are defined in XPB.CH.  The default
pointer is XBPWINDOW_POINTERTYPE_POINTER.  <naCursor> may be a
numeric resource ID that points to a Bit-Map that has been
compiled with the resource compiler and linked to the .EXE.
<naCursor> may be a 3-element array described as follows:

  Element  Type  Description
  -------  ---- ---------------------------------------------
    [1]      C   Optional name of .DLL containing the pointer
                 resource.

    [2]      N   The numeric resource ID of the pointer.  If
                 element 1 is a NIL, then this resource must be
                 linked into the .EXE.

    [3]      N   The type of resource as defined in XBP.CH.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

COLOR <ncFGc>, <ncBGc> are foreground and background colors.
They may be character strings representing valid text-based
colors supported by SetColor() or they may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH. If <bncFGc> is a
code block is must return a 2-element array containing a
foreground and background color.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.
The object is passed as a parameter to the code block.

GOTFOCUS <bGotFocus> is a code block that is evaluated when this
object receives input focus.  <bGotFocus> := {|uNIL1,uNIL2,self|...}

LOSTFOCUS <bLostFocus> is a code block that is evaluated when this
object loses input focus.  <bLostFocus> := {|uNIL1,uNIL2,self|...}

TABSTOP will cause the object (Xbase Part) to be set when using
the Tab key.  Note: When logical groups are defined in a dialog
using TABGROUP <nTabGroup>, TABSTOP is usually set to .T. (true)
for the first dialog element in the group.  This allows the first
dialog element of a group to be activated using the Tab key.

NOTABSTOP will cause the object (Xbase Part) to be ignored when
using the Tab key. This clause is needed only to override any
default setting of TabStop by the DCGETOPTIONS [TABSTOP] command.

TABGROUP <nTabGroup> allows objects (Xbase Parts) that are created
immediately after one another in the GetList to be combined into
logical groups. This allows the user to navigate within a dialog
from group to group by pressing the Tab key.  Within a group of
dialog elements navigation is performed using the cursor keys.

Only constants defined in the XBP.CH file can be used as values
for this instance variable.  The following table lists the
available constants:

#define constants for <nTabGroup>:

 Constant             Description

 XBP_NO_GROUP     *)  Dialog element does not belong to a group
 XBP_BEGIN_GROUP      Dialog element is the first in a group
                      (this begins the definition of the group)
 XBP_WITHIN_GROUP     Dialog element is within a group
 XBP_END_GROUP        Dialog element is the last in a group
                      (this ends the definition of the group)

*) Default value

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS

VSCROLL is used to attach a vertical scroll bar to the right side
of parent object <oParentV> and scroll the static window within
the range of <nVStart> and, <nVEnd>.  For best results the static
window created by this DCSTATIC command should be a child of
<oParentV>.  The optional clause OBJECT <oObjectV> is used to
store a pointer to the scrollbar object.  See the example.

HSCROLL is used to attach a horizontal scroll bar to the bottom
of parent object <oParentH> and scroll the static window within
the range of <nHStart> and, <nHEnd>.  For best results the static
window created by this DCSTATIC command should be a child of
<oParentH>.  The optional clause OBJECT <oObjectH> is used to
store a pointer to the scrollbar object.  See the example.

RESIZE <aResize> is an optional array of two (2) elements
used for resizing and repositioning the object when the parent
is resized.

NOTE: RESIZE is to be used in conjunction with the RESIZE clause
      of DCGETOPTIONS. See the RESIZE clause of DCGETOPTIONS for
      examples.

      The optional SCALEFONT clause will automatically scale the
      font size up or down when the object is resized.

RESTYPE <cResType> provides support for bitmap resources of type
BMP, PNG, GIF and JPEG that have been linked into a .RES file to
be used as the caption.

Example:

@ .. DCPUSHBUTTON CAPTION 2000 RESTYPE GIF

// myres.arc
USERDEF GIF
2000 = FILE ".\GIFChart.GIF"

RESFILE <cResFile> is the name of the .DLL that contains the
resource stated in the RESTYPE <cResType> clause.  If this parameter
is not used, then the resource must be in the .EXE.

DRAG <bDrag> is a codeblock to evaluate when the left mouse button
is clicked in the object and the drag is started.  The return
value of the code block will be stored in memory to be later
retrieved by the Drop operation. A pointer to the clicked on
object is passed to the code block.

DIALOG <bDD> is a codeblock that will evaluate when the drag is
started.  This is used to call a function that will create a
dialog window which will move with the mouse during the drag.
The dialog window will be destroyed upon the drop operation
or the release of the mouse.

Ex: DRAG {|o|o:getData()} DIALOG {|mp1,mp2,oXbp|DragDialog(mp1,mp2,oXbp)} ;

DROP <bDrop> is a codeblock to evaluate when the left mouse button
is released in the object and the drag is ended.  A pointer to
the object and the value stored in memory at the start of the
Drag are passed to the code block.

CURSOR <nDropCursor> is the mouse cursor that will show when it
is moved over this object during a drag operation.

Ex: DROP {|o,x|o:setData(x),o:invalidateRect()} ;
       CURSOR CURSOR POINTER_DATADROP_ASSIGN

SUBCLASS <cSubClass> is a string containing a class name that
will be used to create the class, rather than DC_XbpStatic().
This class should inherit from DC_XbpStatic().
See the example in \exp19\samples\subclass.

FORMATTED is used to allow for displaying of formatted text with
bold, italic, underline, tabbed or indented characters.  See the
sample program in .\samples\static\formatted.prg

Notes:

The object created by @ DCSTATIC is an object of the XbpStatic() class, therefore it can be manipulated with any iVar or method supported by XbpStatic().

Examples:

#include "dcdialog.ch"

* -- Example 1 -- *

PROCEDURE Xtest()

LOCAL GetList := {}, oStatic1

@ 0,0 DCSTATIC XBPSTATIC_TYPE_RECESSEDBOX SIZE 20,4 ;
   OBJECT oStatic1

@ 6,0 DCSTATIC XBPSTATIC_TYPE_RAISEDBOX SIZE 20,4

@ 2,1 DCSTATIC XBPSTATIC_TYPE_TEXT SIZE 15,1 ;
   CAPTION 'This is text' PARENT oStatic1

DCREAD GUI ;
   TITLE 'Static Demo' ;
   FIT ;
   ADDBUTTONS

RETURN

*-- Example 2 --*

FUNCTION ScrollTest()

LOCAL GetList := {}, oStatic1, oStatic2, oStatic3, i, aGets[20]

@ 0,0 DCSTATIC TYPE XBPSTATIC_TYPE_RECESSEDBOX SIZE 40,10 ;
      OBJECT oStatic1

@ .5,1 DCSTATIC TYPE XBPSTATIC_TYPE_TEXT SIZE 38,9 ;
      OBJECT oStatic2

@ 1,1 DCSTATIC TYPE XBPSTATIC_TYPE_TEXT SIZE 70,25 ;
      OBJECT oStatic3 ;
      PARENT oStatic2 ;
      FONT '12.Alaska Crt' ;
      VSCROLL oStatic1 RANGE 0,500 ;
      HSCROLL oStatic1 RANGE 0,500

FOR i := 1 TO 20
  aGets[i] := i
  @ i-1,1 DCSAY Str(i,2) + ;
    ' This................is.................Get ' + ;
    Str(i,2) GET aGets[i] PICT '99999' ;
    SAYSIZE 0 PARENT oStatic3
NEXT

DCREAD GUI FIT ADDBUTTONS TITLE 'Scrolling a Static Window'

RETURN nil

Files:

DCDIALOG.CH


@ DCTABPAGE

Create a TAB PAGE object for displaying with GUI reader

The command @..DCTABPAGE creates a new Tab Page object and adds the object to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> @..DCTABPAGE objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCRADIO, @..DCPUSHBUTTON or @..DCMULTILINE.<br><br>

Syntax:

@ <nSRow>,<nSCol> DCTABPAGE <oGroup> ;
    [SIZE <nWidth>, <nHeight>] ;
    [TYPE <nType>] ;
    [TABHEIGHT <nTabH>] ;
    [TABWIDTH <nTabW>] ;
    [PREOFFSET <nPre>] ;
    [POSTOFFSET <nPost>] ;
    [PARENT <oParent>] ;
    [PARENTID <cParentId>] ;
    [GROUP <nGroup>] ;
    [CAPTION <cText>] ;
    [CARGO <xCargo>] ;
    [MESSAGE <bcMsg>] ;
    [HELPCODE <cHelpCode>] ;
    [COLOR <ncColor> [,<ncDisabled>] ] ;
    [COLOR <bColor>] ;
    [WHEN <bWhen>] ;
    [FONT <bocFont>] ;
    [HIDE <bHide>] ;
    [VALID <bValid>] ;
    [PIXEL] ;
    [TOOLTIP <bcToolTip>] ;
    [MESSAGE <cMsg> [INTO <oMsgBox>]] ;
    [CURSOR <naCursor>] ;
    [RELATIVE <oRel>] ;
    [PREEVAL <bPreEval>] ;
    [EVAL <bEval>] ;
    [ID <cId>] ;
    [TITLE <cTitle>] ;
    [ACCELKEY <anAccel>] ;
    [GOTFOCUS <bGotFocus>] ;
    [LOSTFOCUS <bLostFocus>] ;
    [TABSTOP]  ;
    [NOTABSTOP];
    [TABGROUP <nTabGroup>] ;
    [VISIBLE] ;
    [INVISIBLE] ;
    [GROUP <cGroup>] ;
    [STATICAREA <oStaticArea>] ;
    [ANGLE <nAngle>] ;
    [RESIZE <aResize> [SCALEFONT] ] ;
    [RESTYPE <cResType>] ;
    [RESFILE <cResFile>] ;
    [MINIMIZEDCOLOR <anMinColorFG>, <anMinColorBG>] ;
    [MAXIMIZEDCOLOR <anMaxColorFG>, <anMaxColorBG>] ;
    [DRAG <bDrag> [DIALOG <bDD>] ;
    [DROP <bDrop> [CURSOR <nDropCursor>] ;
    [SUBCLASS <cSubClass>] ;
    [IMAGE <ocnImage>] ;
    [SELECTEDIMAGE <ocnSelectedImg>] ;                                     ;
    [DISABLEDIMAGE <ocnDisabledImg>] ;
    [IMAGEALIGN <nImageAlign>] ;
    [TEXTALIGN <nTextAlign>] ;
    [CAPTIONLAYOUT <nCaptionLayout>] ;
    [MERGECHILDREN]                                    ;

Returns:

Arguments:
<nSRow>, <nSCol> are the coordinates on the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object unless the RELATIVE argument is used.
If no parent is assigned, then the parent is the Dialogue box.
IF the PIXEL option is set to .TRUE. in DCGETOPTIONS, then
the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel
mode by including PIXEL as a command argument.

CAPTION <cCaption> is the caption to place on the tab. The caption
may be a string, resource, bitmap object or the name of an image
that exists on a mapped drive or UNC.

Examples:  @ .. DCTABPAGE .. CAPTION '\exp18\bitmaps\pencil.bmp'
           @ .. DCTABPAGE .. CAPTION 'Pencil'
           @ .. DCTABPAGE .. CAPTION BITMAP_PENCIL_S

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.  This option also allows for the automatic
sizing of the TabPage, Tab Widths, and Tab locations.

SIZE <nWidth>, <nHeight> defines the size of the tabpage.
If no size is given, then the tabpage will be automatically
sized to fit the parent window.  IF the PIXEL option is set to
.TRUE. in DCGETOPTIONS, then the numbers are in pixels,
otherwise they are in standard text-based coordinates.  You
can also force the pixel mode by including PIXEL in the command.
It is recommended that the SIZE parameters be used only on the
first tabpage in a set and that all other tabpages be established
as "relative" to the previous tabpage.  Assigning a tabpage as
RELATIVE to a previous tabpage will cause the TabPage size to be
the same size as the previous tabpage.

TYPE <nType> is one of the #define constants XBPTABPAGE_TAB_TOP
or XBPTABPAGE_TAB_BOTTOM.  TYPE will determine whether to
display the tab at the top or bottom of the page. The default
is top.

<oGroup> is the name of the variable to assign as a storage
place for this object.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object. If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

MESSAGE <bcMsg> is the message you want to display in the
message area of the dialogue screen defined by the DCMESSAGEBOX
command when the object is in focus.  Optionally, INTO <oMsgBox>
will designate which message box to display the message into.
If the INTO clause is not used, then the last message box in the
GetList is the default. <oMsgBox> may also be any object that
supports the :setCaption() method.  If <bcMsg> is a code-block,
it must return a character string.

HELPCODE <cHelp> is a character string that is passed to the
DC_HelpF1() function if F1 is pressed when the mouse is placed
over any area of the tab page that does not contain an object.
The help code is used by the Help system to override the
passing of the Procedure and Varname for more specific
context-help.

TABHEIGHT <nTabH> is the height of the tab (in pixels).  The
default height is calculated automatically as 1.5 times the
height of the title bar of the window. This is usually 33
pixels. If <nTabH> is set to zero, no tab is displayed.

TABWIDTH <nTabW> is the width of the tab.  The numeric value is
in text-based columns unless the PIXEL clause is used.  This
optional clause is intended to be used in lieu of the PREOFFSET
and POSTOFFSET clauses because it is simpler.  It should also
be used only on the first TabPage of a group of relative
tabpages.  All relative TabPages will inherit this width.

PREOFFSET <nPre> and POSTOFFSET <nPost> are numeric values
used to determine the starting and ending position of each tab.
The numeric values are percentage values from 0 to 100 for the
for the percentage of the offset.  See the XbpTabPage()
documentation for more information.  If a value is not given then
a PREOFFSET of 0 and a POSTOFFSET of 85 are default.  It is
recommended that PREOFFSET/POSTOFFSET be used only on the first
tabpage in a set and that all other tabpages be established as
"relative" to the previous tabpage.  Assigning a tabpage as
RELATIVE to a previous tabpage will cause the Tab Size and
location to be automatically assigned.

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the TabPage object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.

FONT <cFont> is a character string defining an optional font.
The font string must conform to the Xbase++ standard, ie.
"10.Courier Bold". It may also be a font object or a code block
that returns a character string or a font object to later
refresh with DC_GetRefresh().

TOOLTIP <bcToolTip> is a character string which will display
as a "Tool Tip" next to the object when the cursor is passed
over the object. A semi-colon within the text indicates a new
line.  If <bcToolTip> is a code-block, it must return a character
string.  NOTE: The Tooltip painting method is run in another
thread, therefore the codeblock should not run code that points
to the current work area.  It may however, contain local, public
or private variables.

CURSOR <naCursor> may be either a numeric value or an array of
3 elements which defines an optional mouse pointer to use for
this object.  System mouse pointers start with
XBPWINDOW_POINTERTYPE_ and are defined in XPB.CH.  The default
pointer is XBPWINDOW_POINTERTYPE_POINTER.  <naCursor> may be a
numeric resource ID that points to a Bit-Map that has been
compiled with the resource compiler and linked to the .EXE.
<naCursor> may be a 3-element array described as follows:

  Element  Type  Description
  -------  ---- ---------------------------------------------
    [1]      C   Optional name of .DLL containing the pointer
                 resource.

    [2]      N   The numeric resource ID of the pointer.  If
                 element 1 is a NIL, then this resource must be
                 linked into the .EXE.

    [3]      N   The type of resource as defined in XBP.CH.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

VALID <bValid> is a code block to evaluate when the tabpage
is minimized and another tabpage is selected.  This code block
must return a logical value.  If the value returned is .TRUE.
then the tabpage will be minimized otherwise another tabpage
cannot be selected.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

COLOR <ncColor>, <ncDisabled> are enabled and disabled colors.
The tabpage will be set to the enable color if the WHEN clause
evaluates .TRUE. and to the disabled color if the WHEN clause
evaluates .FALSE.  They must be numeric constants which begin
with either the prefix GRA_CLR_ or the prefix XBPSYSCLR_ as
defined in GRA.CH or XBP.CH. If <bncColor> is a code block is
must return a 2-element array containing an enabled and
disabled color.

COLOR <bColor> may be a code block that returns a foreground
and background color in an array of 2 numeric elements.  This
allows colors to be changed dynamically.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the tabpage will be disabled and grayed.
If the value returned is .TRUE. then the tabpage will be enabled.
The object is passed as a parameter to the code block.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the tabpage will be hidden from view.  If
the value returned is .FALSE. then the tabpage will be displayed.
The object is passed as a parameter to the code block.

ACCELKEY <anAccel> is a numeric "hot-key" assignment that will set
focus to the tabpage object when the hot-key is pressed.  The key
must be a valid key with the prefix xbeK_*.  These keys are
defined in APPEVENT.CH.  <anAccel> may also be an array of numeric
values to assign more than one key to the object.

GOTFOCUS <bGotFocus> is a code block that is evaluated when this
object receives input focus.  <bGotFocus> := {|uNIL1,uNIL2,self|...}

LOSTFOCUS <bLostFocus> is a code block that is evaluated when this
object loses input focus.  <bLostFocus> := {|uNIL1,uNIL2,self|...}

TABSTOP will cause the object (Xbase Part) to be set when using
the Tab key.  Note: When logical groups are defined in a dialog
using TABGROUP <nTabGroup>, TABSTOP is usually set to .T. (true)
for the first dialog element in the group.  This allows the first
dialog element of a group to be activated using the Tab key.

NOTABSTOP will cause the object (Xbase Part) to be ignored when
using the Tab key. This clause is needed only to override any
default setting of TabStop by the DCGETOPTIONS [TABSTOP] command.

TABGROUP <nTabGroup> allows objects (Xbase Parts) that are created
immediately after one another in the GetList to be combined into
logical groups. This allows the user to navigate within a dialog
from group to group by pressing the Tab key.  Within a group of
dialog elements navigation is performed using the cursor keys.

Only constants defined in the XBP.CH file can be used as values
for this instance variable.  The following table lists the
available constants:

#define constants for <nTabGroup>:

 Constant             Description

 XBP_NO_GROUP     *)  Dialog element does not belong to a group
 XBP_BEGIN_GROUP      Dialog element is the first in a group
                      (this begins the definition of the group)
 XBP_WITHIN_GROUP     Dialog element is within a group
 XBP_END_GROUP        Dialog element is the last in a group
                      (this ends the definition of the group)

*) Default value

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS

STATICAREA <oStaticArea> will create an XbpStatic object covering
the entire area of the TabPage.  This is a text-type static which
will appear to be invisible.  This clause should be used when
placing @..DCSAY..GET or DCGET objects on a Tab page and the
HILITE <nColor> clause of DCGETOPTIONS is used to hilite the
currently selected GET.  The gets should use <oStaticArea> as the
parent rather than <oTabPage> to prevent the TabPage from looking
strange after highlighting gets - this is an Xbase++ anomoly.

ANGLE <nAngle> is used to put a beveled edge on the sides of
the tab.  This is a numeric value from 0 - 90.

RESIZE <aResize> is an optional array of two (2) elements
used for resizing and repositioning the object when the parent
is resized.

NOTE: RESIZE is to be used in conjunction with the RESIZE clause
      of DCGETOPTIONS. See the RESIZE clause of DCGETOPTIONS for
      examples.

      The optional SCALEFONT clause will automatically scale the
      font size up or down when the object is resized.

RESTYPE <cResType> provides support for bitmap resources of type
BMP, PNG, GIF and JPEG that have been linked into a .RES file to
be used as the caption.

Example:

@ .. DCPUSHBUTTON CAPTION 2000 RESTYPE GIF

// myres.arc
USERDEF GIF
2000 = FILE ".\GIFChart.GIF"

RESFILE <cResFile> is the name of the .DLL that contains the
resource stated in the RESTYPE <cResType> clause.  If this parameter
is not used, then the resource must be in the .EXE.

MINIMIZEDCOLOR <anMinColorFG>, <anMinColorBG> is the foreground and
background color when the tabpage is minimized. Each argument may
be a numeric GRA* color or an array of 3 RGB values.

MAXIMIZEDCOLOR <anMaxColorFG>, <anMaxColorBG> is the foreground and
background color when the tabpage is maximized.Each argument may
be a numeric GRA* color or an array of 3 RGB values.

Note: the above colors will override the colors defined by
DC_TabPageColor().

DRAG <bDrag> is a codeblock to evaluate when the left mouse button
is clicked in the object and the drag is started.  The return
value of the code block will be stored in memory to be later
retrieved by the Drop operation. A pointer to the clicked on
object is passed to the code block.

DIALOG <bDD> is a codeblock that will evaluate when the drag is
started.  This is used to call a function that will create a
dialog window which will move with the mouse during the drag.
The dialog window will be destroyed upon the drop operation
or the release of the mouse.

Ex: DRAG {|o|o:getData()} DIALOG {|mp1,mp2,oXbp|DragDialog(mp1,mp2,oXbp)} ;

DROP <bDrop> is a codeblock to evaluate when the left mouse button
is released in the object and the drag is ended.  A pointer to
the object and the value stored in memory at the start of the
Drag are passed to the code block.

CURSOR <nDropCursor> is the mouse cursor that will show when it
is moved over this object during a drag operation.

Ex: DROP {|o,x|o:setData(x),o:invalidateRect()} ;
       CURSOR CURSOR POINTER_DATADROP_ASSIGN

SUBCLASS <cSubClass> is a string containing a class name that
will be used to create the class, rather than DC_XbpTabPage().
This class should inherit from DC_XbpTabPage().
See the example in \exp19\samples\subclass.

IMAGE <ocnImage> is an image to display on the tab.  This may be
the name of an image file or icon, a numeric index or an XbpIcon
or XbpBitmap object.

SELECTEDIMAGE <ocnSelectedImg> is the image to display only when
the tabpage is selected.

DISABLEDIMAGE <ocnDisabledImg> is the image to display only when
the tabpage is disabled.

IMAGEALIGN <nImageAlign> is a numeric value that defines how the
image should be aligned on the tab.  The value can be any value
starting with XBP_ALIGN* that is defined in XBP.CH.

TEXTALIGN <nTextAlign> is a numeric value that defines how the
text should be aligned on the tab. The value can be any value
starting with XBP_ALIGN* that is defined in XBP.CH.

CAPTIONLAYOUT <nCaptionLayout> is a numeric value that defines
how the image and text should be aligned with relation to each
other.  The value can be any value starting with XBP_LAYOUT_* that
is defined in DCDIALOG.CH.

The MERGECHILDREN option is used to improve performance when creating
dialogs that have tabpages with many child objects.  Tabpages that
use this options will not create the child objects until the tabpage
receives focus the first time.  See the sample TabMerge.Prg program
in the \exp19\samples\tabpage folder.

Notes:
 The TabPage object created by @ DCTABPAGE is an object of the XbpTabPage() class, therefore it can be manipulated with any iVar or method supported by XbpTabPage().

 Navigation between Tab-Pages is accomplished via the following keys:

 Key                         Action ------------------------  ------------------------------------ Control-Tab               Select Next Tab-Page Control-Shift-Tab         Select Previous Tab-Page

Examples:
#include 'dcdialog.ch'

PROCEDURE Xtest()

LOCAL oTabPage1, oTabPage2, oTabPage3, cDesc := Space(30),;
      aType := {'Star-Trek','Hollywood','Sports','Other'},;
      cType := Space(15), dDateOrig := Date(), dDateAcqu := Date(),;
      nOrigPrice := 0, nApprValue := 0, cMemo := '', ;
      GetList := {}

/* ---- Tab Page #1 ---- */

@  0,0 DCTABPAGE oTabPage1 CAPTION 'Collection' ;
   SIZE 72,15 PREOFFSET 0 POSTOFFSET 85

@  3,2  DCSAY "Description" GET cDesc SAYRIGHT PARENT oTabPage1

@  5,10  DCSAY "Type" PARENT oTabPage1 SAYSIZE 8

@  6,10 DCCOMBOBOX cType LIST aType SIZE 12,6 PARENT oTabPage1

/* ---- Tab Page #2 ---- */

@  0,0 DCTABPAGE oTabPage2 CAPTION 'Financial' ;
   RELATIVE oTabPage1

@  4,2 DCSAY "  Original Date" GET dDateOrig  PICT '99/99/9999' ;
   PARENT oTabPage2 SAYRIGHT

@  6,2 DCSAY "  Acquired Date" GET dDateAcqu  PICT '99/99/9999' ;
   PARENT oTabPage2 SAYRIGHT

@  8,2 DCSAY " Acquired Price" GET nOrigPrice PICT '9999.99'  ;
   PARENT oTabPage2 SAYRIGHT

@ 10,2 DCSAY "Appraised Value" GET nApprValue PICT '9999.99'  ;
   PARENT oTabPage2 SAYRIGHT

/* ---- Tab Page #3 ---- */

@  0,0 DCTABPAGE oTabPage3 CAPTION 'Memo' ;
   RELATIVE oTabPage2

@  5,2 DCMULTILINE cMemo PARENT oTabPage3 SIZE 65,8 ;
   FONT "10.Courier.Bold"

DCREAD GUI ;
   TITLE 'Tab-Page Demo' ;
   FIT ;
   ADDBUTTONS

RETURN

Files:
DCDIALOG.CH


@ DCTOOLBAR

Create a TOOLBAR object for displaying with GUI reader

The command @ DCTOOLBAR creates a new ToolBar object and adds the object to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> Even though a toolbar can be created with a DCSTATIC object and DCPUSHBUTTON objects, the DCTOOLBAR command is much simpler to use for toolbars because it can optionally anchor the toolbar to the top, left, bottom, or right border of the main dialogue box or the parent. DCTOOLBAR is used with DCADDBUTTON to add pushbuttons to the toolbar.<br><br> DCTOOLBAR objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCRADIO, @..DCPUSHBUTTON or @..DCMULTILINE.<br><br>

Syntax:

[@ <nSRow>, <nSCol>] DCTOOLBAR <oToolBar> ;
    [TYPE <nType>] ;
    [FANCY] ;
    [VERTICAL] ;
    [HORIZONTAL] ;
    [SIZE <nWidth> [,<nHeight>]] ;
    [BUTTONSIZE <nBWidth>, [<nBHeight>]] ;
    [PARENT <oParent>] ;
    [PARENTID <cParentId>] ;
    [PRESENTATION <aPres>] ;
    [COLOR <ncFgC> [,<ncBgC>] ] ;
    [WHEN <bWhen>] ;
    [HIDE <bHide>] ;
    [CARGO <xCargo>] ;
    [PIXEL] ;
    [PREEVAL <bPreEval>] ;
    [EVAL <bEval>] ;
    [ID <cId>] ;
    [CURSOR <naCursor>] ;
    [TITLE <cTitle>] ;
    [GROUP <cGroup>] ;
    [VISIBLE] ;
    [INVISIBLE] ;
    [RESIZE <aResize>] ;
    [FIT]
    ;

   [ALIGN <nAlign>] ;
    [DRAG <bDrag> [DIALOG <bDD>] ;
    [DROP <bDrop> [CURSOR <nDropCursor>] ;
    [SUBCLASS <cSubClass>] ;
    [BUTTONCONFIG <oButtonConfig>]

Arguments:

<nSRow>, <nSCol> are the optional coordinates on the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object unless the RELATIVE argument is used.
If no parent is assigned, then the parent is the Dialogue box.
IF the PIXEL option is set to .TRUE. in DCGETOPTIONS, then
the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel
mode by including PIXEL as a command argument.

<oToolBar> is the name of the variable to assign as a storage
place for this object.

TYPE <nType> is the type of toolbar.  ToolBars are created using
XbpStatic() objects, so valid constants start with the prefix
XBPSTATIC_TYPE_ and are listed in XBP.CH.  The default is
XBPSTATIC_TYPE_RAISEDBOX.

FANCY will cause all buttons to be displayed in a special mode
in which the button will be displayed only as a caption on the
toolbar until the mouse is passed over the caption which will
then display the raised button.  DC_FancyButtonMode(1) can be
used to override this clause and force normal buttons.
CAUTION: FANCY cannot be used with a button captions that are
bitmap objects, however it can be used with captions that are
bitmap resources.

VERTICAL or HORIZONTAL is required only if the orientation of
the buttons on the toolbar cannot be automatically determined
by the width/height ratio of the toolbar.  For example, by
default a toolbar with a width greater than the height would
automatically stack buttons from left to right.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.  If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

SIZE <nWidth>, <nHeight> optionally define the size of the
toolbar.  If no size is given, then the toolbar will be
automatically sized to fit the parent window.  IF the PIXEL
option is set to .TRUE. in DCGETOPTIONS, then the numbers are
in pixels otherwise they are in standard text-based coordinates.
You can also force the pixel mode by including PIXEL in the
command.

BUTTONSIZE <nBWidth>, <nBHeight> optionally define the size of
the buttons which will be added to the toolbar via the DCADDBUTTON
command in the event that the SIZE clause of the DCADDBUTTON
command is not used.

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the Toolbar object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the object will be disabled and grayed.
If the value returned is .TRUE. then the object will be enabled.
The object is passed as a parameter to the code block.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the toolbar will be hidden from view.  If
the value returned is .FALSE. then the toolbar will be displayed.
The object is passed as a parameter to the code block.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETOBJECT() to determine the status
of a get object.

CURSOR <naCursor> may be either a numeric value or an array of
3 elements which defines an optional mouse pointer to use for
this object.  System mouse pointers start with
XBPWINDOW_POINTERTYPE_ and are defined in XPB.CH.  The default
pointer is XBPWINDOW_POINTERTYPE_POINTER.  <naCursor> may be a
numeric resource ID that points to a Bit-Map that has been
compiled with the resource compiler and linked to the .EXE.
<naCursor> may be a 3-element array described as follows:

  Element  Type  Description
  -------  ---- ---------------------------------------------
    [1]      C   Optional name of .DLL containing the pointer
                 resource.

    [2]      N   The numeric resource ID of the pointer.  If
                 element 1 is a NIL, then this resource must be
                 linked into the .EXE.

    [3]      N   The type of resource as defined in XBP.CH.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS

COLOR <ncFGc>, <ncBGc> are foreground and background colors.
They may be character strings representing valid text-based
colors supported by SetColor() or they may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH. If <bncFGc> is a
code block is must return a 2-element array containing a
foreground and background color.

RESIZE <aResize> is an optional array of two (2) elements
used for resizing and repositioning the object when the parent
is resized.

NOTE: RESIZE is to be used in conjunction with the RESIZE clause
      of DCGETOPTIONS. See the RESIZE clause of DCGETOPTIONS for
      examples.

FIT causes the toolbar to be resized to the sum of the width of
all the child buttons.

ALIGN <nAlign> is a special alignment option. If the
ALIGN DCGUI_ALIGN_RIGHT clause is used, then the column coordinate
defines the right-most position of the toolbar.  If the ALIGN
DCGUI_ALIGN_CENTER clause is used, then the column coordinate
defines the center of the toolbar. See the sample program in
.\SAMPLES\TOOLBAR.

DRAG <bDrag> is a codeblock to evaluate when the left mouse button
is clicked in the object and the drag is started.  The return
value of the code block will be stored in memory to be later
retrieved by the Drop operation. A pointer to the clicked on
object is passed to the code block.

DIALOG <bDD> is a codeblock that will evaluate when the drag is
started.  This is used to call a function that will create a
dialog window which will move with the mouse during the drag.
The dialog window will be destroyed upon the drop operation
or the release of the mouse.

Ex: DRAG {|o|o:getData()} DIALOG {|mp1,mp2,oXbp|DragDialog(mp1,mp2,oXbp)} ;

DROP <bDrop> is a codeblock to evaluate when the left mouse button
is released in the object and the drag is ended.  A pointer to
the object and the value stored in memory at the start of the
Drag are passed to the code block.

CURSOR <nDropCursor> is the mouse cursor that will show when it
is moved over this object during a drag operation.

Ex: DROP {|o,x|o:setData(x),o:invalidateRect()} ;
       CURSOR CURSOR POINTER_DATADROP_ASSIGN

SUBCLASS <cSubClass> is a string containing a class name that
will be used to create the class, rather than DC_XbpToolBar().
This class should inherit from DC_XbpToolBar().
See the example in \exp19\samples\subclass.

BUTTONCONFIG <oButtonConfig> is use to apply a DC_XbpPushButtonConfig()
object as the default for all successive DCADDBUTTON commands.
This may be used to configure legacy toolbars to use the
DC_XbpPushButtonXP() class.

Notes:

The toolbar object created by @ DCTOOLBAR is an object of the XbpStatic() class, therefore it can be manipulated with any iVar or method supported by XbpStatic().

Examples:

#include "dcdialog.ch"
#include "dcbitmap.ch"

PROCEDURE Xtest()

LOCAL GetList := {}, oToolBar

DCTOOLBAR oToolBar ALIGN TOOLBAR_TOP

DCADDBUTTON PARENT oToolBar CAPTION 'Exit' ;
            SIZE 9 ;
            ACTION {||DC_ReadGuiEvent(DCGUI_EXIT_OK)}

DCADDBUTTON PARENT oToolBar CAPTION 'Open' ;
            SIZE 9 ;
            ACTION {||OpenFile()}

DCADDBUTTON PARENT oToolBar CAPTION 'Close' ;
            SIZE 9 ;
            ACTION {||CloseFile()}

DCREAD GUI FIT ADDBUTTONS

RETURN

/* ---------------------- */

STATIC PROCEDURE OpenFile()

DC_MsgBox('File is now open')

RETURN

/* ---------------------- */

STATIC PROCEDURE CloseFile()

DC_MsgBox('File has been closed')

RETURN

Files:

DCDIALOG.CH

See Also:

   DCADDBUTTON
   dc_fancybuttonmode()


@ DCTREEARRAY

Browse a multi-dimensional array using Tree-View

The command @..DCTREEARRAY creates a new Tree Array object and adds the object to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> @..DCTREEARRAY is used to browse a multi-dimensional array using a Tree-View style dialog.<br><br>

Syntax:

@ <nRow>, <nCol> DCTREEARRAY <aArray> ;
       [ VAR <xVar> ] ;
       [ PARENT <oParent> ]       ;
       [ COLOR <fgC> [, <bgC> ] ] ;
       [ FONT <bocFont> ]          ;
       [ DATALINK <bLink> ]       ;
       [ SIZE <nWidth> [, <nHeight>] ] ;
       [ TITLE <title> ]          ;
       [ HIDE <bHide> ]           ;
       [ WHEN <bWhen> ]           ;
       [ PREEVAL <bPreEval> ]     ;
       [ EVAL <bEval> ]           ;
       [ RELATIVE <oRel> ]        ;
       [ OPTIONS <aOptions> ]     ;
       [ OBJECT <oObject> ]       ;
       [ ID <cId> ]               ;
       [ HASBUTTONS ]             ;
       [ HASLINES ]               ;
       [ GOTFOCUS <bGotFocus> ]   ;
       [ LOSTFOCUS <bLostFocus> ] ;
       [ TABSTOP ]                ;
       [ NOTABSTOP ]              ;
       [ VISIBLE ]                ;
       [ INVISIBLE ]              ;
       [ TABGROUP <nTabGroup> ]   ;
       [ GROUP <cGroup> ]                                            ;

Arguments:

<nRow> and <nCol> are the row and column of the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE <oRel> argument is
used.  If no parent is assigned, then the parent is the Dialog
box. IF the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel
mode by including PIXEL as a command argument.

<aArray> is the multi-dimensional array to browse.

VAR <xVar> is the name of a local variable to store the value
of the array item that is selected by the user.

DATALINK <bLink> is a code block that is evaluated each time
a new item is selected in the tree browse.

OBJECT <oObject> is the variable to use as a container for the
object after it is created by the GUI reader.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

FONT <cFont> is a character string defining an optional font.
The font string must conform to the Xbase++ standard, ie.
"10.Courier Bold". It may also be a font object or a code block
that returns a character string or a font object to later
refresh with DC_GetRefresh().

SIZE <nWidth> [,<nHeight>]] is the size to allocate to the
Tree View window.  If the PIXEL option is set to .TRUE. in
DCGETOPTIONS, then the size must be entered in pixels otherwise
it must be entered in standard text length.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object. If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the object will be disabled and grayed.
If the value returned is .TRUE. then the object will be enabled.
The object is passed as a parameter to the code block.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.
The object is passed as a parameter to the code block.

COLOR <ncFGc>, <ncBGc> are foreground and background colors.
They may be character strings representing valid text-based
colors supported by SetColor() or they may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH. If <bncFGc> is a
code block is must return a 2-element array containing a
foreground and background color.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETOBJECT() to determine the status
of a get object.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

GOTFOCUS <bGotFocus> is a code block that is evaluated when this
object receives input focus.

LOSTFOCUS <bLostFocus> is a code block that is evaluated when this
object loses input focus.

TABSTOP will cause the object (Xbase Part) to be set when using
the Tab key.  Note: When logical groups are defined in a dialog
using TABGROUP <nTabGroup>, TABSTOP is usually set to .T. (true)
for the first dialog element in the group.  This allows the first
dialog element of a group to be activated using the Tab key.

NOTABSTOP will cause the object (Xbase Part) to be ignored when
using the Tab key. This clause is needed only to override any
default setting of TabStop by the DCGETOPTIONS [TABSTOP] command.

TABGROUP <nTabGroup> allows objects (Xbase Parts) that are created
immediately after one another in the GetList to be combined into
logical groups. This allows the user to navigate within a dialog
from group to group by pressing the Tab key.  Within a group of
dialog elements navigation is performed using the cursor keys.

Only constants defined in the XBP.CH file can be used as values
for this instance variable.  The following table lists the
available constants:

#define constants for <nTabGroup>:

 Constant             Description

 XBP_NO_GROUP     *)  Dialog element does not belong to a group
 XBP_BEGIN_GROUP      Dialog element is the first in a group
                      (this begins the definition of the group)
 XBP_WITHIN_GROUP     Dialog element is within a group
 XBP_END_GROUP        Dialog element is the last in a group
                      (this ends the definition of the group)

*) Default value

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override

OPTIONS <aRef> is an optional reference array that is used to
format the data in the browse.  If <aRef> is a NIL then the tree
view will display the exact contents of the array.  <aRef> is an
array of 5-element sub-arrays, 1 for each level of the array
being browsed. The sub-arrays are defined as follows:

Element Type Description
------- ---- ----------------------------------------------------

  [1]     B  Optional code block used to format the displayed
             data.  The array item and it's ordinal position
             within the array are passed as parameters.
             examples: {|a,n|a[1]}
                       {|a,n|filedata(a,n)}

  [2]     N  The resource ID of a bitmap or icon image to
             visualize the normal state of the array item
             (not marked and not expanded).

  [3]     N  The resource ID of a bitmap or icon image to
             visualize the marked state of the array item.

  [4]     N  The resource ID of a bitmap or icon image to
             visualize the expanded state of the array item.

  [5]     A  An optional array of numeric values containing
             the array elements to include in the expanded
             view.

HASBUTTONS displays a Plus or Minus sign at each node of the
tree. This indicates whether the next level of the tree can be
expanded or suppressed.

HASLINES displays lines between the nodes of the tree and their
leaves. This results in a more readable display.

Notes:

The object created by @ DCTREEARRAY is an object of the XbpTreeView() class, therefore it can be manipulated with any iVar or method supported by XbpTreeView().

Examples:

#INCLUDE "dcicon.ch"
#INCLUDE "dctree.ch"

FUNCTION Xtest()

LOCAL aDirectory, aDirOptions, Getlist := {}, oDirtree1, oDirtree2

aDirectory := Directory( '*.*' )
IF Len(aDirectory) > 50
  ASize(aDirectory,50)
ENDIF

aDirOptions := { { {|a,n|a[1]},         ;
                   ICON_CLOSEDFOLDER, ;
                   ICON_CLOSEDFOLDER, ;
                   ICON_OPENFOLDER }, ;
                 { {|a,n|FileData(a,n)}, ;
                   ICON_CLOSEDFOLDER, ;
                   ICON_CLOSEDFOLDER, ;
                   ICON_OPENFOLDER, ;
                   { 2,3,4,7,8 } } }

@ 2, 5 DCTREEARRAY aDirectory SIZE 40,13 ;
       OBJECT oDirTree1 OPTIONS aDirOptions

@ 2,45 DCTREEARRAY aDirectory SIZE 40,13 ;
       OBJECT oDirTree2

DCREAD GUI FIT BUTTONS DCGUI_BUTTON_EXIT ;
   TITLE 'Directory Browsers'

RETURN nil

/* ------------------- */

STATIC FUNCTION FileData ( xData, nElement )

LOCAL cData := DC_XtoC( xData ), cPrefix

DO CASE
  CASE nElement = 2
    cPrefix := 'File Size: '
  CASE nElement = 3
    cPrefix := 'File Date: '
  CASE nElement = 4
    cPrefix := 'File Time: '
  CASE nElement = 7
    cPrefix := 'Creation Date: '
  CASE nElement = 8
    cPrefix := 'Creation Time: '
  OTHERWISE
    cPrefix := ''
ENDCASE

RETURN cPrefix + cData

Files:

DCTREE.CH

See Also:

   dc_guiabrowse()


@ DCTREEROOT

Create a Root object for a Tree View

The command DCTREEROOT creates a new TreeView root object and adds the object to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> DCTREEROOT is used with the DCTREEITEM command to create a TreeView system for viewing any kind of data.

Syntax:

@ <nRow>, <nCol> DCTREEROOT  ;
     [ PARENT <oParent> ] ;
     [ COLOR <fgC> [, <bgC> ] ] ;
     [ FONT <bocFont> ] ;
     [ SIZE <nWidth> [, <nHeight>] ] ;
     [ HIDE <bHide> ] ;
     [ WHEN <bWhen> ] ;
     [ PREEVAL <bPreEval> ] ;
     [ EVAL <bEval> ] ;
     [ RELATIVE <oRel> ] ;
     [ OBJECT <oObject> ] ;
     [ ID <cId> ] ;
     [ TOOLTIP <cToolTip> ] ;
     [ TITLE <title> ] ;
     [ ACCELKEY <anAccel> ] ;
     [ HASBUTTONS ] ;
     [ HASLINES ] ;
     [ ALWAYSSHOWSELECTION ] ;
     [ GOTFOCUS <bGotFocus> ] ;
     [ LOSTFOCUS <bLostFocus> ] ;
     [ TABSTOP ] ;
     [ NOTABSTOP ] ;
     [ VISIBLE ] ;
     [ INVISIBLE ] ;
     [ TABGROUP <nTabGroup> ] ;
     [ GROUP <cGroup> ] ;
     [ ITEMCOLLAPSED <bItemCollapsed> ] ;
     [ ITEMEXPANDED <bItemExpanded> ] ;
     [ ITEMMARKED <bItemMarked> ] ;
     [ ITEMSELECTED <bItemSelected> ] ;
     [ DRAG <bDrag> [DIALOG <bDD> ] ;
     [ DROP <bDrop> [CURSOR <nDropCursor> ] ;
     [ SUBCLASS <cSubClass> ]

Arguments:

<nRow> and <nCol> are the row and column of the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE argument is used.
If no parent is assigned, then the parent is the Dialog box.
IF the PIXEL option is set to .TRUE. in DCGETOPTIONS, then
the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel
mode by including PIXEL as a command argument.

SIZE <nWidth>,<nHeight> is the width and height of the TreeView
window.  If the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based numbers.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object. If this
argument is not passed then the parent will be the object set
with the DCSETPARENT command.

OBJECT <oObject> is the variable to use as a container for the
object after it is created by the GUI reader.

FONT <cFont> is a character string defining an optional font.
The font string must conform to the Xbase++ standard, ie.
"10.Courier Bold". It may also be a font object or a code block
that returns a character string or a font object to later
refresh with DC_GetRefresh().

MESSAGE <bcMsg> is the message you want to display in the
message area of the dialogue screen defined by the DCMESSAGEBOX
command when the object is in focus.  Optionally, INTO <oMsgBox>
will designate which message box to display the message into.
If the INTO clause is not used, then the last message box in the
GetList is the default.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the object will be disabled and grayed.
If the value returned is .TRUE. then the object will be enabled.
The object is passed as a parameter to the code block.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.
The object is passed as a parameter to the code block.

HELPCODE <cHelp> is a character string that is passed to the
DC_HelpF1() function if F1 is pressed or the HELP button
is clicked when this GET has focus.  This HELPCODE allows
the Help system to override the passing of the Procedure and
Varname for more specific context-help.

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the ComboBox object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.

TOOLTIP <bcToolTip> is a character string which will display
as a "Tool Tip" next to the object when the cursor is passed
over the object. A semi-colon within the text indicates a new
line.  If <bcToolTip> is a code-block, it must return a character
string.  NOTE: The Tooltip painting method is run in another
thread, therefore the codeblock should not run code that points
to the current work area.  It may however, contain local, public
or private variables.

CURSOR <naCursor> may be either a numeric value or an array of
3 elements which defines an optional mouse pointer to use for
this object.  System mouse pointers start with
XBPWINDOW_POINTERTYPE_ and are defined in XPB.CH.  The default
pointer is XBPWINDOW_POINTERTYPE_POINTER.  <naCursor> may be a
numeric resource ID that points to a Bit-Map that has been
compiled with the resource compiler and linked to the .EXE.
<naCursor> may be a 3-element array described as follows:

  Element  Type  Description
  -------  ---- ---------------------------------------------
    [1]      C   Optional name of .DLL containing the pointer
                 resource.

    [2]      N   The numeric resource ID of the pointer.  If
                 element 1 is a NIL, then this resource must be
                 linked into the .EXE.

    [3]      N   The type of resource as defined in XBP.CH.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

COLOR <ncFGc>, <ncBGc> are foreground and background colors.
They may be character strings representing valid text-based
colors supported by SetColor() or they may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH.  IF <bncFGc> is a
code block is must return a 2-element array containing a
foreground and background color.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

ACCELKEY <anAccel> is a numeric "hot-key" assignment that will set
focus to the checkbox object when the hot-key is pressed.  The key
must be a valid key with the prefix xbeK_*.  These keys are
defined in APPEVENT.CH.  <anAccel> may also be an array of numeric
values to assign more than one key to the object.

GOTFOCUS <bGotFocus> is a code block that is evaluated when this
object receives input focus.  <bGotFocus> := {|uNIL1,uNIL2,self|...}

LOSTFOCUS <bLostFocus> is a code block that is evaluated when this
object loses input focus.  <bLostFocus> := {|uNIL1,uNIL2,self|...}

TABSTOP will cause the object (Xbase Part) to be set when using
the Tab key.  Note: When logical groups are defined in a dialog
using TABGROUP <nTabGroup>, TABSTOP is usually set to .T. (true)
for the first dialog element in the group.  This allows the first
dialog element of a group to be activated using the Tab key.

NOTABSTOP will cause the object (Xbase Part) to be ignored when
using the Tab key. This clause is needed only to override any
default setting of TabStop by the DCGETOPTIONS [TABSTOP] command.

TABGROUP <nTabGroup> allows objects (Xbase Parts) that are created
immediately after one another in the GetList to be combined into
logical groups. This allows the user to navigate within a dialog
from group to group by pressing the Tab key.  Within a group of
dialog elements navigation is performed using the cursor keys.

Only constants defined in the XBP.CH file can be used as values
for this instance variable.  The following table lists the
available constants:

#define constants for <nTabGroup>:

 Constant             Description

 XBP_NO_GROUP     *)  Dialog element does not belong to a group
 XBP_BEGIN_GROUP      Dialog element is the first in a group
                      (this begins the definition of the group)
 XBP_WITHIN_GROUP     Dialog element is within a group
 XBP_END_GROUP        Dialog element is the last in a group
                      (this ends the definition of the group)

*) Default value

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS

HASBUTTONS causes the TreeView to display a Plus or Minus sign
at each node of the tree. This indicates whether the next level
of the tree can be expanded or suppressed.

HASLINES causes the TreeView to display lines between the nodes
of the tree and their leaves. This results in a more readable
display.

ALWAYSSHOWSELECTION displays the selected item always highlighted,
even if the tree view has no input focus.

ITEMCOLLAPSED <bItemCollapsed> is a code block that is evaluated
after the sub-items of a DCTREEITEM object are suppressed in
the display. This is achieved by clicking the Minus sign with
the left mouse button, or when the Minus key or left arrow key
is pressed.

ITEMEXPANDED <bItemExpanded> is a code block that is evaluated
after the sub-items of a DCTREEITEM object became visible in
the display. This is achieved by clicking the Plus sign with the
left mouse button, or when the Plus key or right arrow key is
pressed.

ITEMMARKED <bItemMarked> is a code block that is evaluated after
an item is marked within the tree view. This occurs while
navigating with the cursor keys or when an item is clicked.

ITEMSELECTED <bItemSelected> is a code block that is evaluated
after an item is selected. This occurs when an item is double
clicked or by pressing the Return key.

DRAG <bDrag> is a codeblock to evaluate when the left mouse button
is clicked in the object and the drag is started.  The return
value of the code block will be stored in memory to be later
retrieved by the Drop operation. A pointer to the clicked on
object is passed to the code block.

DIALOG <bDD> is a codeblock that will evaluate when the drag is
started.  This is used to call a function that will create a
dialog window which will move with the mouse during the drag.
The dialog window will be destroyed upon the drop operation
or the release of the mouse.

Ex: DRAG {|o|o:getData()} DIALOG {|mp1,mp2,oXbp|DragDialog(mp1,mp2,oXbp)} ;

DROP <bDrop> is a codeblock to evaluate when the left mouse button
is released in the object and the drag is ended.  A pointer to
the object and the value stored in memory at the start of the
Drag are passed to the code block.

CURSOR <nDropCursor> is the mouse cursor that will show when it
is moved over this object during a drag operation.

Ex: DROP {|o,x|o:setData(x),o:invalidateRect()} ;
       CURSOR CURSOR POINTER_DATADROP_ASSIGN

SUBCLASS <cSubClass> is a string containing a class name that
will be used to create the class, rather than DC_XbpTreeView().
This class should inherit from DC_XbpTreeView().
See the example in \exp19\samples\subclass.

Notes:

The object created by @ DCTREEROOT is an object of the XbpTreeView() class, therefore it can be manipulated with any iVar or method supported by XbpTreeView().

Examples:

#include "dctree.ch"

PROCEDURE Xtest()

LOCAL GetList := {}, oTree, oSubTree1, oSubTree2, cSelected

@ 1,1 DCTREEROOT SIZE 30,10 OBJECT oTree CAPTION 'Tree Root' ;
  HASLINES ;
  HASBUTTONS ;
  ITEMSELECTED {|o| cSelected := o:caption, ;
                    DC_ReadGuiEvent(DCGUI_EXIT_OK,GetList)}

DCTREEITEM CAPTION 'SubTree 1' PARENT oTree OBJECT oSubTree1
  DCTREEITEM CAPTION 'Sub-SubTree 1/1' PARENT oSubTree1
  DCTREEITEM CAPTION 'Sub-SubTree 1/2' PARENT oSubTree1
  DCTREEITEM CAPTION 'Sub-SubTree 1/3' PARENT oSubTree1

DCTREEITEM CAPTION 'SubTree 2' PARENT oTree OBJECT oSubTree2
  DCTREEITEM CAPTION 'Sub-SubTree 2/1' PARENT oSubTree2
  DCTREEITEM CAPTION 'Sub-SubTree 2/2' PARENT oSubTree2
  DCTREEITEM CAPTION 'Sub-SubTree 2/3' PARENT oSubTree2

DCREAD GUI FIT ADDBUTTONS

DC_MsgBox({'You Selected:',cSelected})

RETURN nil

Files:

DCTREE.CH

See Also:

   DCTREEITEM


@ SAYWIN

Write a SAY text string in a Text or GUI dialog

The command @..SAYWIN is a Dual-Mode command which allows for writing text to a Text Window, a GUI window or the standard CRT window. This command is included in EXPRESS.CH to replace the standard @..SAY command with @..SAYWIN commands and make it easier to migrate existing Clipper applications with @..SAYs by changing them to @..SAYWIN commands.<br><br> The command functions identical to the standard @..SAY command unless the DCEXPLODE command is used first. DCEXPLODE creates a window on the screen which defines either a Text-area or a GUI dialogue for all successive @..SAYWINs. @..SAYWIN commands will cause the text to be routed either to the text window area or the GUI dialogue window until a DCIMPLODE command is used to destroy the window.<br><br> CAUTION:<br><br> @..SAY commands are translated by EXPRESS.CH to use the Getlist system and the DC_ReadGets() Dual-Mode reader. Including EXPRESS.CH in your application code will treat @..SAY commands as though they are part of a Dialog Getlist.

Syntax:

@ <nRow>,<nCol> SAYWIN <cText> ;
    [COLOR <cColor>] ;
    [PARENT <oParent>] ;
    [FONT <cFont>] ;
    [OK]

Arguments:

PARENT <aParent> is an array of screen information that was
originally returned by DCEXPLODE.  If no parameter is
passed, then the static array posted by the last usage of
DCEXPLODE will be used for the screen information.  If no
call to DCEXPLODE is made since the last call to DCIMPLODE,
then the text is written to the CRT window and treated as
a normal @..SAY.

<nRow> is the row position within the window. If the
FIXED option was used with DCEXPLODE when the window
was created, then this must be a coordinate which is
relative to 0,0 of the screen, otherwise it must be relative
to 0,0 of the window.

<nCol> is the column position within the window. If the
FIXED option was used with DCEXPLODE when the window
was created, then this must be a coordinate which is
relative to 0,0 of the screen, otherwise it must be relative
to 0,0 of the window.

<cText> is the text to display.

The OK clause will display an "OK" button on the bottom
of the Window and pause program execution until the user
hits ENTER or clicks the mouse on the OK button.

FONT <cFont> will override the optional font that was used
with DCEXPLODE for this Say object only, otherwise the
default font will be used.  This parameter is used in GUI
mode only.

COLOR <cColor> is a valid Clipper color string.  If this option
is not used, then the background color of the window will
be used.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the <oMsgBox>:cargo exported variable, however
it will not be stored in the same manner it is entered.  The
:cargo container of DCDIALOG objects is an array of at least
two elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - The value of <xCargo>.

 [3] and up - optional values added by the GUI reader.

Examples:

Files:
EXPRESS.CH


DCADDBUTTON

Add BUTTON to TOOLBAR object for displaying with GUI reader

The command DCADDBUTTON creates a new PushButton object and adds the object to the array named GETLIST which is later processed by the DC_READGETS() function or by the DCREAD command. DCADDBUTTON is used with DCTOOLBAR to add a PushButton to the toolbar. Each button is automatically placed in the next open place on the previously declared ToolBar. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> The GetList is passed to the function DC_READGETS() which looks at the DC_GUI() flag and determines whether to process this list as a standard text-based get screen or as a GUI-based dialogue.<br><br>

Syntax:

DCADDBUTTON ;
    [CAPTION <bcnoCaption>] ;
    [SIZE <nWidth> [,<nHeight>] ] ;
    [TYPE <nType>] ;
    [OBJECT <oButton>] ;
    [ACTION <bAction>] ;
    [PARENT <oParent>] ;
    [PARENTID <cParentId>] ;
    [MESSAGE <bcMsg> [INTO <oMsgBox>]] ;
    [HELPCODE <cHelpCode>] ;
    [COLOR <bncFgC> [,<ncBgC>] ] ;
    [FONT <bocFont>] ;
    [PRESENTATION <aPres>] ;
    [PIXEL] ;
    [TOOLTIP <bcToolTip>] ;
    [OBJECT <oObject>] ;
    [CURSOR <nCursor>] ;
    [PREEVAL <bPreEval>] ;
    [EVAL <bEval>] ;
    [ID <cId>] ;
    [TITLE <cTitle>] ;
    [WHEN <bWhen>] ;
    [HIDE <bHide>] ;
    [ACCELKEY <anAccel>] ;
    [GOTFOCUS <bGotFocus>] ;
    [LOSTFOCUS <bLostFocus>] ;
    [TABSTOP]  ;
    [NOTABSTOP];
    [TABGROUP <nTabGroup>] ;
    [VISIBLE] ;
    [INVISIBLE] ;
    [CARGO <xCargo>] [CARGO "CANCEL"] ;
    [GROUP <cGroup>] ;
    [STATIC] * ;
      [FOCUSCOLOR <nTextColor> [,<nFrameColor>]] * ;
      [BITMAP <xBMUp> [,<xBMDown> [,<xBMNeutral> [,<xBMFlash>]]]] * ;
      [FLASH <nFlashIterations> [,<nFlashDelay>]] ;
      [REGION <aRegion>] *
    [RESTYPE <cResType>] ;
    [RESFILE <cResFile>];
    [ALIGNCAPTION <nAlign>] ;
    [SOUND <cSound>] ;
    [SCALEBITMAP] ;
    [DRAG <bDrag> [DIALOG <bDD>] ;
    [DROP <bDrop> [CURSOR <nDropCursor>]

  * Supported by eXPress++ 1.7 or later

Arguments:

CAPTION <bcnoCaption> is the part of the PushButton object that
is displayed within the area of the pushbutton. The caption may
be one of the following:

1) A character string.  An ampersand (&) preceding a character in
   the text assigns the ALT-<char> key as a hotkey for the
   pushbutton and underlines the character.  A tilde (~) preceding
   the character will only underline the character and will not
   enable the hot-key.  A tilde (~) could be used with the
   ACCELKEY clause to establish the hot key(s).

2) A bitmap resource. The numeric resource ID of the bitmap is
   assigned to the instance variable.  If a resource ID is used,
   it must be defined in a resource file that is linked to the
   EXE file using the resource compiler.

3) A bitmap object created with the XbpBitMap() class. (Xbase++
   1.7 or later).

4) A two-element array.  This array must contain either two
   character strings, two bitmap objects or two bitmap numeric
   values.  The first value is the caption to use when the
   pushbutton is "enabled" by the WHEN clause.  The second value
   is the caption to use when the pushbutton is "disabled" by
   the WHEN clause.

4. A code block.  A code block is evaluated whenever the
   DC_GetRefresh() function is called.  This is used to change
   the caption dynamically after the pushbutton object is created.
   The code block must return either a character string, a bitmap
   numeric resource, a bitmap object or an array of 2 elements.

OBJECT <oButton> is an optional variable name to assign to this
button for storage of the XbpPushbutton() object after the
dialogue screen is painted.  This provides a LOCAL variable
as a pointer to the button object.

ACTION <bAction> is a code block that gets evaluated when
the button is activated.

PARENT <oParent> is the name of the variable that was
assigned to the parent ToolBar for this Button.  A ToolBar object
is created by the @ DCTOOLBAR command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

SIZE <nWidth>, <nHeight> optionally defines the size of the
button.  If no size is given, then the button will be
automatically sized to fit the parent toolbar based on option
clauses used via the DCTOOLBAR command.  If the BUTTONSIZE
clause of the DCTOOLBAR command is used, then the button will be
sized accordingly, otherwise the wdith will be equal to the
height.  IF the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based coordinates. You can also force the pixel mode by
including PIXEL in the command.

TYPE <nType> is used for displaying a SEPARATOR rather than an
action button.  <nType> may be any numerical value starting with
XBPSTATIC_TYPE_* defined in XBP.CH.

MESSAGE <bcMsg> is the message you want to display in the
message area of the dialogue screen defined by the DCMESSAGEBOX
command when the object is in focus.  Optionally, INTO <oMsgBox>
will designate which message box to display the message into.
If the INTO clause is not used, then the last message box in the
GetList is the default. If <bcMsg> is a code-block, it must
return a character string.

HELPCODE <cHelp> is a character string that is passed to the
DC_HelpF1() function if F1 is pressed when the mouse is placed
over the button. The help code is used by the Help system to
for specific context-help.

TOOLTIP <bcToolTip> is a character string which will display
as a "Tool Tip" next to the object when the cursor is passed
over the object. A semi-colon within the text indicates a new
line.  If <bcToolTip> is a code-block, it must return a character
string.  NOTE: The Tooltip painting method is run in another
thread, therefore the codeblock should not run code that points
to the current work area.  It may however, contain local, public
or private variables.

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the Button object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.

CURSOR <naCursor> may be either a numeric value or an array of
3 elements which defines an optional mouse pointer to use for
this object.  System mouse pointers start with
XBPWINDOW_POINTERTYPE_ and are defined in XPB.CH.  The default
pointer is XBPWINDOW_POINTERTYPE_POINTER.  <naCursor> may be a
numeric resource ID that points to a Bit-Map that has been
compiled with the resource compiler and linked to the .EXE.
<naCursor> may be a 3-element array described as follows:

  Element  Type  Description
  -------  ---- ---------------------------------------------
    [1]      C   Optional name of .DLL containing the pointer
                 resource.

    [2]      N   The numeric resource ID of the pointer.  If
                 element 1 is a NIL, then this resource must be
                 linked into the .EXE.

    [3]      N   The type of resource as defined in XBP.CH.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

COLOR <ncFGc>, <ncBGc> are foreground and background colors.
They may be character strings representing valid text-based
colors supported by SetColor() or they may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH. If <bncFGc> is a
code block is must return a 2-element array containing a
foreground and background color.  The COLOR clause is supported
only when using the STATIC clause.

FONT <cFont> is a character string defining an optional font.
The font string must conform to the Xbase++ standard, ie.
"10.Courier Bold". It may also be a font object or a code block
that returns a character string or a font object to later
refresh with DC_GetRefresh().

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETOBJECT() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the object will be disabled and grayed.
If the value returned is .TRUE. then the object will be enabled.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.

ACCELKEY <anAccel> is a numeric "hot-key" assignment that will set
focus to the checkbox object when the hot-key is pressed.  The key
must be a valid key with the prefix xbeK_*.  These keys are
defined in APPEVENT.CH.  <anAccel> may also be an array of numeric
values to assign more than one key to the object.

GOTFOCUS <bGotFocus> is a code block that is evaluated when this
object receives input focus.  <bGotFocus> := {|uNIL1,uNIL2,self|...}

LOSTFOCUS <bLostFocus> is a code block that is evaluated when this
object loses input focus.  <bLostFocus> := {|uNIL1,uNIL2,self|...}

TABSTOP will cause the object (Xbase Part) to be set when using
the Tab key.  Note: When logical groups are defined in a dialog
using TABGROUP <nTabGroup>, TABSTOP is usually set to .T. (true)
for the first dialog element in the group.  This allows the first
dialog element of a group to be activated using the Tab key.

NOTABSTOP will cause the object (Xbase Part) to be ignored when
using the Tab key. This clause is needed only to override any
default setting of TabStop by the DCGETOPTIONS [TABSTOP] command.

TABGROUP <nTabGroup> allows objects (Xbase Parts) that are created
immediately after one another in the GetList to be combined into
logical groups. This allows the user to navigate within a dialog
from group to group by pressing the Tab key.  Within a group of
dialog elements navigation is performed using the cursor keys.

Only constants defined in the XBP.CH file can be used as values
for this instance variable.  The following table lists the
available constants:

#define constants for <nTabGroup>:

 Constant             Description

 XBP_NO_GROUP     *)  Dialog element does not belong to a group
 XBP_BEGIN_GROUP      Dialog element is the first in a group
                      (this begins the definition of the group)
 XBP_WITHIN_GROUP     Dialog element is within a group
 XBP_END_GROUP        Dialog element is the last in a group
                      (this ends the definition of the group)

*) Default value

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS

The following options are supported by eXPress++ 1.7 or later:

When the STATIC * clause is used, a class created from the
XbpDialog() class is used instead of the XbpPushButton() class.
This allows for the creation of complex pushbuttons by allowing
the pushbutton object to be a parent for any other object such
as DCSTATIC or DCSAY for the display of text, icons, bitmaps
etc. on the button.

FOCUSCOLOR * is used to determine the color of any text on the
button when it receives focus by passing the mouse over the button.
<anTextColor> is the color of the text.  If this argument is a
NIL the text color will not be changed.  <anFrameColor> is the
color of a frame that is drawn around the perimeter of the button
to hilight the button when it receives focus.  If this argument
is a NIL, there will be no frame drawn.  These arguments may be
be a numeric color defined by GRA_CLR_* in GRA.CH or a 3 element
array of RGB colors.

BITMAP * <xBMUp> is the background bitmap for the button in the
UP (unpressed) condition.  <xBMDown> is the background bitmap for
the button in the DOWN (pressed) condition and <xBMNeutral> is the
background bitmap of the button in the NEUTRAL (fancy button)
condition.  <xBMFlash> is the bitmap to be used with the FLASH
clause.  Each bitmap will be replicated over the entire pushbutton
background area.  The bitmaps may be numeric resources,
XbpBitMap() objects, or character strings containing a .BMP, .GIF,
or .JPG file name.

FLASH is used with the <xBMFlash> bitmap.  This bitmap will flash
on just before the action block is evaluated.  This feature is for
touch-screen applications or other applications where some kind of
tactile feedback is desired to indicate to the user that the button
has been pressed.  <nFlashIterations> is the number of times that
the bitmap should flash.  <nFlashDelay> is the amount of delay in
100th/second between flashes.

REGION <aRegion> is an array defining the region of the button
to display.  All other areas will be removed.  <aRegion> may be
an array that is created by DC_RegionArray() or may be any other
multidimensional array containing a set of rectangular regions.
<aRegion> is used to display the button as a circle, ellipse,
octagon, diamond, or other irregular shape.

RESTYPE <cResType> provides support for bitmap resources of type
BMP, PNG, GIF and JPEG that have been linked into a .RES file to
be used as the caption.

Example:

@ .. DCPUSHBUTTON CAPTION 2000 RESTYPE GIF

// myres.arc
USERDEF GIF
2000 = FILE ".\GIFChart.GIF"

RESFILE <cResFile> is the name of the .DLL that contains the
resource stated in the RESTYPE <cResType> clause.  If this parameter
is not used, then the resource must be in the .EXE.

ALIGNCAPTION <nAlign> is a set of options to use to align the text
on the PushButton.  The options are numerical definitions
starting with BS_* and are defined in DCDIALOG.CH.

Note the most common option is BS_MULTILINE.

SOUND <cSound> is the name of a .WAV file to play when the button
is clicked.

SCALEBITMAP will shrink or enlarge a bitmap caption to fit
exactly within the button size.  Note: bitmaps should be 24-bit
(hi-color) for this to work correctly.

DRAG <bDrag> is a codeblock to evaluate when the left mouse button
is clicked in the object and the drag is started.  The return
value of the code block will be stored in memory to be later
retrieved by the Drop operation. A pointer to the clicked on
object is passed to the code block.

DIALOG <bDD> is a codeblock that will evaluate when the drag is
started.  This is used to call a function that will create a
dialog window which will move with the mouse during the drag.
The dialog window will be destroyed upon the drop operation
or the release of the mouse.

Ex: DRAG {|o|o:getData()} DIALOG {|mp1,mp2,oXbp|DragDialog(mp1,mp2,oXbp)} ;

DROP <bDrop> is a codeblock to evaluate when the left mouse button
is released in the object and the drag is ended.  A pointer to
the object and the value stored in memory at the start of the
Drag are passed to the code block.

CURSOR <nDropCursor> is the mouse cursor that will show when it
is moved over this object during a drag operation.

Ex: DROP {|o,x|o:setData(x),o:invalidateRect()} ;
       CURSOR CURSOR POINTER_DATADROP_ASSIGN

Notes:

If the STATIC clause is not used, the object created by DCADDBUTTON is an object of the XbpPushButton() class, therefore it can be manipulated with any iVar or method supported by XbpPushButton() class.

If the STATIC clause is used, the object created by DCADDBUTTON is an object of the XbpDialog() class, therefore it can be manipulated with any iVar or method supported by the XbpDialog() class (eXPress++ version 1.7 or later).

Use the clause CARGO 'CANCEL' if the pushbutton is to be used to exit a dialog without testing validations. This will insure that if the pushbutton is clicked while in a DCGET with a validation the validation code block will not be evaluated.

For an example of STATIC buttons, run XDEMO.EXE (sample group 5).

Examples:

#include "dcdialog.ch"
#include "dcbitmap.ch"

PROCEDURE Xtest()

LOCAL GetList := {}, oToolBar

DCTOOLBAR oToolBar ALIGN TOOLBAR_TOP

DCADDBUTTON PARENT oToolBar CAPTION 'Exit' ;
            SIZE 9 ;
            ACTION {||DC_ReadGuiEvent(DCGUI_EXIT_OK)}

DCADDBUTTON PARENT oToolBar CAPTION 'Open' ;
            SIZE 9 ;
            ACTION {||OpenFile()}

DCADDBUTTON PARENT oToolBar CAPTION 'Close' ;
            SIZE 9 ;
            ACTION {||CloseFile()}

DCREAD GUI FIT ADDBUTTONS

RETURN

/* ---------------------- */

STATIC PROCEDURE OpenFile()

DC_MsgBox('File is now open')

RETURN

/* ---------------------- */

STATIC PROCEDURE CloseFile()

DC_MsgBox('File has been closed')

RETURN

Files:

DCDIALOG.CH

See Also:

   @ DCPUSHBUTTON
   @ DCTOOLBAR
   dc_regionarray()


DCADDBUTTONXP

Add XP-Style BUTTON to TOOLBAR object

The command DCADDBUTTONXP creates a new XP-Style PushButton object and adds the object to the array named GETLIST which is later processed by the DC_READGETS() function or by the DCREAD command. DCADDBUTTONXP is used with DCTOOLBAR to add a PushButton to the toolbar. Each button is automatically placed in the next open place on the previously declared ToolBar. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> The GetList is passed to the function DC_READGETS() which looks at the DC_GUI() flag and determines whether to process this list as a standard text-based get screen or as a GUI-based dialogue.

Syntax:

DCADDBUTTONXP <parameters...>

See @ DCPUSHBUTTONXP for the command parameters.

Notes:

This command or class is only available in Xbase++ 1.9 (build 331 or later) because it uses the ownerdraw capability of the XbpPushButton() class.

Use the clause CARGO 'CANCEL' if the pushbutton is to be used to exit a dialog without testing validations. This will insure that if the pushbutton is clicked while in a DCGET with a validation the validation code block will not be evaluated.

For an example of DCADDBUTTONXP buttons, see the sample program in \exp19\samples\buttonxp.

The function DC_BitmapTransparentColor() may be used to set the default transparent color for pushbuttons that have bitmaps as captions.

DCADDBUTTONXP objects are created from the DC_XbpPushButtonXP() class which is derived from the XbpPushButton() class.

Designing DCADDBUTTONXP objects to look exactly the way you would want can be a time-consuming task, therefore it is recommended that you use a special utility program for this purpose. See \exp19\samples\buttonxp\buttpicker.exe.

Files:

DCDIALOG.CH

See Also:

   @ DCTOOLBAR
   @ DCPUSHBUTTON
   @ DCPUSHBUTTONXP
   DC_XbpPushButtonXPConfig()


DCAPPBROWSE

Create an APPLICATION BROWSE object for displaying with GUI reade

DCAPPBROWSE is an adaption of the Xbase Application Parts command APPBROWSE to the DCDIALOG Getlist system. APPBROWSE is a very powerful command that allows to program standardized browse dialogs for databases in a comfortable way. It creates an object of the AppBrowse class and adds Xbase Parts, which access database fields (note: an AppBrowse object is a container for Xbase Parts). Although the command has many options it is easy to use. The minimum requirements to display an edit dialog are two lines of code: <br><br> USE Customer NEW DCAPPBROWSE DCREAD GUI ADDBUTTONS FIT <br><br> These two lines open a database (USE) and add an AppBrowse object (DCAPPBROWSE) to the GetList for later display by the DCREAD GUI command. The AppBrowse window contains columns for all fields of the database. <br><br> Options for display <br><br> Key word Description <br><br> 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 HILITE Defines colors for the column selection bar STYLE Defines display style <br><br> See the APPBROWSE command in the Xbase++ documentation for more information.

Syntax:

DCAPPBROWSE INTO <oBrowse> ;
  [ PARENT <oParent> ] ;
  [ FIELDS <fields,...> ] ;
  [ COLOR <fgC> [, <bgC> ] ] ;
  [ HILITE <fgHC> [, <bcHC> ] ] ;
  [ FONT <(font)> ] ;
  [ POSITION <nRow> [, <nCol>] ] ;
  [ SIZE <nWidth> [, <nHeight>] [<per:PERCENT>] ] ;
  [ TITLE <title> ] ;
  [ ALIGN <cAlign:LEFT,CENTER,RIGHT> ] ] ;
  [ FONT <(hFont)>] ;
  [ STYLE <style> ] ;
  [ ALIAS <(alias)> ] ;
  [ FOR <bFor> ] ;
  [ EVAL <bEval> ] ;
  [ RELATIVE <oRel> ] ;
  [ GROUP <cGroup> ] ;
  [ ID <cId> ] ;
  [ VISIBLE ] ;
  [ INVISIBLE ]

Arguments:

INTO <oBrowse> is the name of the memory variable that gets the
AppBrowse object assigned which is created by the DCAPPBROWSE
command. If the INTO clause is used it must appear as the first
option of the DCAPPBROWSE command.  If it is not used the object
is assigned to the variable appObject.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.  If this
clause is not used, then the object will be displayed in the
top-level dialogue screen.

FIELDS <fields,...> specifies a comma-separated list of field
names to be edited in the AppEdit window. The field names can be
specified as literals or as character expressions in parentheses.
If particular fonts or colors should be used for single fields
the DCAPPFIELD command must be used for field specification.
This is also the case when calculation fields are to be
displayed.

If neither the FIELDS option nor command DCAPPFIELD is used, all
fields of the current work area are displayed as columns in the
AppBrowse window.

POSITION <pos1> [, <pos2>] positions an AppBrowse window.  If not
specified the AppBrowse window is displayed at the point {0,0}
(bottom left corner of the parent).

There are three possibilities to position an AppBrowse object.
Depending on the data types used for <pos1> and/or <pos2> the
AppBrowse window can be positioned absolute or relative in its
parent window.  In addidion, text orientde (row, column) or
graphic coordinates (x,y) may be used:

Coordinates to position an AppBrowse window

 <pos1>    Value    <pos2>    Value   Description

 Array     {nX,nY}  n.a.      NIL     <pos1> is an array containing
                                      grafic coordinates for the
                                      AppBrowse 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 AppBrowse 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

The key word SIZE defines the size of an AppBrowse window. As with
POSITION, the size can be specified using graphic or text oriented
coordinates. Additionaly, percentage values may be used. The next
table shows different possibilities:

Coordinates used for size definition of an AppBrowse window

 <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

If a numeric value is used for <size1> and/or <size2> in conjunction
with the key word PERCENT, the values are interpreted as percentage
of the parent window's height and/or width.

TITLE <cTitle> is a character expression which is displayed in the
title bar of an AppBrowse window.  It defaults to the alias name of
the current work area.

COLOR <nForeGround> [, <nBackGround> ] specifies foreground and
background color for the :drawingArea of the AppBrowse window.
#define constants from XBP.CH or GRA.CH must be used
(XBPSYSCLR_* or GRA_CLR_*).

FONT <cFontCompoundName> optionally specifies a character string
defining the compound name of the font to be selected for the
Browse columns (see also the :setFontCompoundName() method of
Xbase Parts).

STYLE 3D | PLAIN | FANCY | <nStyle> defines the style, or the
appearance, of an AppEdit window.  Default styles are selected
specifying either option 3D, PLAIN, or FANCY.  Optionally, styles
can be defined by adding constants listed in the next table, and
using the result for <nStyle> :

Constants for style definition of an AppBrowse window

 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_RAISED           Frames appear in raised style
 APPSTYLE_HORIZONTAL       Fields are positioned horizontally row by row

ALIAS <cAlias> specifies the alias name for the work area to be
used for database navigation by the AppBrowse object.  It defaults
to the current work area.

FOR <lForCondition> is an optional logical expression defining a
condition, or a code block with a logical return value.  Only
records for which  <lForCondition> returns the value .T. (true)
can be edited.  This allows to edit a subset of database records.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETOBJECT() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS

Examples:

 #include "dcapp.ch"
 #include "xbp.ch"
 #include "gra.ch"
 #include "appevent.ch"

 PROCEDURE XTest()

 LOCAL oTabPage1, oTabPage2, oStatic1, oStatic2, GetList := {},;
       GetOptions, oAppEdit, oAppBrowse, oToolBar

 USE COLLECT NEW SHARED

 /* ---- Tab Page #1 ---- */

 @  0,0 DCTABPAGE oTabPage1 CAPTION 'Edit' ;
    SIZE 80,20.5 PREOFFSET 0 POSTOFFSET 85 ;
    COLOR GRA_CLR_BLUE

 @  1.5,1 DCSTATIC XBPSTATIC_TYPE_RAISEDBOX SIZE 78,18.5 ;
    GROUP oStatic1 PARENT oTabPage1

 DCAPPEDIT INTO oAppEdit STYLE PLAIN POSITION 0,0 PARENT oStatic1

 /* ---- Tab Page #2 ---- */

 @  0,0 DCTABPAGE oTabPage2 CAPTION 'Browse' ;
    RELATIVE oTabPage1 ;
    COLOR GRA_CLR_RED

 @  1.5,1 DCSTATIC XBPSTATIC_TYPE_RAISEDBOX SIZE 78,18.5 ;
    GROUP oStatic2 PARENT oTabPage2

 DCAPPBROWSE INTO oAppBrowse STYLE FANCY POSITION 0,0 PARENT oStatic2

 /* ---- Tool Bar ---- */

 DCTOOLBAR oToolBar ALIGN TOOLBAR_RIGHT SIZE 7.1

 DCADDBUTTON CAPTION '&Exit' ;
             PARENT oToolBar ;
             SIZE 7,1 ;
             ACTION {||DC_ReadGuiEvent(DCGUI_EXIT_OK)}

 DCGETOPTIONS WINDOW HEIGHT 440 ;
               WINDOW WIDTH 620

 DCREAD GUI ;
   OPTIONS GetOptions ;
   TITLE "Application Edit/Browse Demo"

 CLOSE collect

 RETURN

Files:

DCAPP.CH

See Also:

   DCREAD GUI
   dc_readgui()


DCAPPEDIT

Create an APPLICATION EDIT object for displaying with GUI reader

DCAPPEDIT is an adaption of the Xbase Application Parts command APPEDIT in the DCDIALOG Getlist system. 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 (note: an AppEdit object is a container for Xbase Parts). Although the command has many options it is easy to use. The minimum requirements to display an edit dialog are two lines of code: <br><br> USE Customer NEW DCAPPEDIT DCREAD GUI ADDBUTTONS FIT<br><br> These two lines open a database (USE) and add an AppEdit object (DCAPPEDIT) to the GetList for later display by the DCREAD GUI command. 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 DCAPPEDIT command are used to configure the edit window in detail or to specify the fields and pushbuttons to be displayed. <br><br> Options for display <br><br> Key word Description <br><br> 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 <br><br> STYLE Defines display style NOACTION Suppresses default controls BITMAP Defines a background bitmap <br><br> See the APPEDIT command in the Xbase++ documentation for more information.

Syntax:

DCAPPEDIT INTO <oEdit> ;
  [ PARENT <oParent> ] ;
  [ FIELDS <fields,...> ] ;
  [ COLOR <fgC> [, <bgC> ] ] ;
  [ FONT <(font)> ] ;
  [ POSITION <nRow> [, <nCol>] ] ;
  [ SIZE <nWidth> [, <nHeight>] [<per:PERCENT>] ] ;
  [ TITLE <title> ] ;
  [ CAPTION [ FONT <(cFont)>] ;
  [ ALIGN <cAlign:LEFT,CENTER,RIGHT> ] ] ;
  [ HEADING <(head)> ] ;
  [ STYLE <style> ] ;
  [ NOACTION <suppress> ] ;
  [ ALIAS <(alias)> ] ;
  [ SEEK <bSeek> ] ;
  [ FOR <bFor> ] ;
  [ WHILE <bWhile> ] ;
  [ TRIGGER <bDelete> [ON] DELETE ] ;
  [ TRIGGER <bInsert> [ON] INSERT ] ;
  [ TRIGGER <bUpdate> [ON] UPDATE ] ;
  [ BITMAP <bitmap> ;
  [ <fit:FIT> ]  ;
  [ EVAL <bEval> ] ;
  [ RELATIVE <oRel> ] ;
  [ GROUP <cGroup> ] ;
  [ ID <cId> ] ;
  [ VISIBLE ] ;
  [ INVISIBLE ]

Arguments:

INTO <oEdit> is the name of the memory variable that gets the
AppEdit object assigned which is created by the DCAPPEDIT command.
If the INTO clause is used it must appear as the first option of
the DCAPPEDIT command.  If it is not used the object is assigned
to the variable appObject.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.  If this
clause is not used, then the object will be displayed in the
top-level dialogue screen.

FIELDS <fields,...> specifies a comma-separated list of field
names to be edited in the AppEdit window. The field names can be
specified as literals or as character expressions in parentheses.
If particular fonts or colors should be used for single fields
the DCAPPFIELD command must be used for field specification.
This is also the case when calculation fields are to be
displayed.

If neither the FIELDS option nor command DCAPPFIELD is used, all
fields of the current work area are displayed in the AppEdit
window.

POSITION <pos1> [, <pos2>] positions an AppEdit window.  If not
specified the AppEdit window is displayed at the point {0,0}
(bottom left corner of the parent).

There are three possibilities to position an AppEdit object.
Depending on the data types used for <pos1> and/or <pos2> the
AppEdit window can be positioned absolute or relative in its
parent window.  In addidion, text orientde (row, column) or
graphic coordinates (x,y) may be used:

Coordinates to position an AppEdit window

 <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

The key word SIZE defines the size of an AppEdit window. As with
POSITION, the size can be specified using graphic or text oriented
coordinates. Additionaly, percentage values may be used. The next
table shows different possibilities:

Coordinates used for size definition of an AppEdit window

 <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

If a numeric value is used for <size1> and/or <size2> in conjunction
with the key word PERCENT, the values are interpreted as percentage
of the parent window's height and/or width.

TITLE <cTitle> is a character expression which is displayed in the
title bar of an AppEdit window.  It defaults to the alias name of
the current work area.

COLOR <nForeGround> [, <nBackGround> ] specifies foreground and
background color for the :drawingArea of the AppEdit window.
#define constants from XBP.CH or GRA.CH must be used
(XBPSYSCLR_* or GRA_CLR_*).

FONT <cFontCompoundName> optionally specifies a character string
defining the compound name of the font to be selected for the
:drawingArea of the AppEdit window (see also the
:setFontCompoundName() method of Xbase Parts).

HEADING <headingOptions> initiates the definition of a heading
to be displayed in the AppEdit Window.  The minimum requirement
for <headingOptions> is a character string to be used as heading.
Optionally, the COLOR clause can be used to define a foreground
and shadow color, a font can be selected with FONT, and the
heading can be aligned with ALIGN LEFT|CENTER|RIGHT. The complete
HEADING otpions are:

    HEADING <cHeadingText> ;
    [ COLOR <nForeGround> [, <nShadow>] ] ;
    [ ALIGN LEFT | CENTER | RIGHT ] ;

    [  FONT <cFontCompoundName> ]

CAPTION <captionOptions> defines color, font and alignment for
the captions of edit controls. The complete CAPTION options are:

    CAPTION ;
    [ COLOR <nForeGround> [, <nShadow>] ] ;
    [ ALIGN LEFT | CENTER | RIGHT ] ;

    [  FONT <cFontCompoundName> ]

NOACTION <nSuppress> allows to suppress single or all default
controls of an AppEdit window.  Values for <nSuppress> are
#define constants that must be added.  The following table lists
all possible constants:

Constants to suppress default controls

 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

BITMAP <nBitmapID> [ FIT ] specifies the resource ID of a
bitmap which is to be displayed in the background of an AppEdit
window.  Without the option FIT, the bitmap is displayed
repeatedly until it has filled the entire display area.  If FIT
is used, the bitmap is displayed once, and scaled to the size of
the display area of the AppEdit window.

STYLE 3D | PLAIN | FANCY | <nStyle> defines the style, or the
appearance, of an AppEdit window.  Default styles are selected
specifying either option 3D, PLAIN, or FANCY.  Optionally, styles
can be defined by adding constants listed in the next table, and
using the result for <nStyle> :

Constants for style definition of an AppEdit window

 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

ALIAS <cAlias> specifies the alias name for the work area to be
used for database navigation by the AppEdit object.  It defaults
to the current work area.

FOR <lForCondition> is an optional logical expression defining a
condition, or a code block with a logical return value.  Only
records for which  <lForCondition> returns the value .T. (true)
can be edited.  This allows to edit a subset of database records.

WHILE <lWhileCondition> is an optional logical expression defining
a condition, or a code block with a logical return value.  It is
evaluated after database navigation.  The AppEdit window is
automatically closed when <lWhileCondition> yields .F. (false).

SEEK <exprSeek> is a literal numeric expression or a code block
with a numeric return value.  It is evaluated after the "Seek"
pushbutton is clicked.  This allows to embed user defined search
routines into the AppEdit window.  The numeric return value of
<exprSeek> must correspond to an APPOP_* #define constant
(see below).

TRIGGER <deleteFunc> ON DELETE is a character string with the
name of a user defined function.  It is called when the "Delete"
pushbutton is clicked.  Alternately, a code block can be
specified for <deleteFunc>.  The return value of the function, or
code block, must correspond to an APPOP_* #define constant
(see below).

TRIGGER <insertFunc> ON INSERT is a character string with the
name of a user defined function.  It is called when the "Save"
pushbutton is clicked while the AppEdit window is in INSERT
mode.  This mode is activated by clicking the "New" pushbutton.
Alternately, a code block can be specified for <insertFunc>.
The return value of the function, or code block, must correspond
to an APPOP_* #define constant (see below).

TRIGGER <updateFunc> ON UPDATE is a character string with the
name of a user defined function.  It is called when the "Save"
pushbutton is clicked while an existing record is edited.
Alternately, a code block can be specified for <updateFunc>.
The return value of the function, or code block, must correspond
to an APPOP_* #define constant (see below).

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETOBJECT() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS

Examples:

 #include "dcapp.ch"
 #include "xbp.ch"
 #include "gra.ch"
 #include "appevent.ch"

 PROCEDURE Xtest()

 LOCAL GetList := {}, GetOptions, oTabPage1, oTabPage2, oTabPage3, ;
       oStatic1, oStatic2, oStatic3, oToolBar, oAppEdit1, oAppEdit2, ;
       oAppEdit3

 USE COLLECT NEW SHARED

 /* ---- Tab Page #1 ---- */

 @  0,0 DCTABPAGE oTabPage1 CAPTION 'Plain' ;
    SIZE 80,20.5 PREOFFSET 0 POSTOFFSET 85 ;
    COLOR GRA_CLR_BLUE

 @  1.5,1 DCSTATIC XBPSTATIC_TYPE_RAISEDBOX SIZE 78,18.5 ;
    GROUP oStatic1 PARENT oTabPage1

 DCAPPEDIT INTO oAppEdit1 STYLE PLAIN POSITION 0,0 PARENT oStatic1

 /* ---- Tab Page #2 ---- */

 @  0,0 DCTABPAGE oTabPage2 CAPTION '3D' ;
    RELATIVE oTabPage1 ;
    COLOR GRA_CLR_RED

 @  1.5,1 DCSTATIC XBPSTATIC_TYPE_RAISEDBOX SIZE 78,18.5 ;
    GROUP oStatic2 PARENT oTabPage2

 DCAPPEDIT INTO oAppEdit2 STYLE 3D POSITION 0,0 PARENT oStatic2

 /* ---- Tab Page #3 ---- */

 @  0,0 DCTABPAGE oTabPage3 CAPTION 'Fancy' ;
    RELATIVE oTabPage2 ;
    COLOR GRA_CLR_YELLOW

 @  1.5,1 DCSTATIC XBPSTATIC_TYPE_RAISEDBOX SIZE 78,18.5 ;
    GROUP oStatic3 PARENT oTabPage3

 DCAPPEDIT INTO oAppEdit3 STYLE FANCY POSITION 0,0 PARENT oStatic3

 /* ---- Tool Bar ---- */

 DCTOOLBAR oToolBar ALIGN TOOLBAR_RIGHT SIZE 7.1

 DCADDBUTTON CAPTION '&Exit' ;
             PARENT oToolBar ;
             SIZE 7,1 ;
             ACTION {||DC_ReadGuiEvent(DCGUI_EXIT_OK)}

 DCGETOPTIONS WINDOW HEIGHT 440 ;
               WINDOW WIDTH 620

 DCREAD GUI ;
   OPTIONS GetOptions ;
   TITLE 'Application Edit Demo'

 CLOSE collect

 RETURN

Files:

DCAPP.CH

See Also:

   DCREAD GUI
   dc_readgui()


DCAPPFIELD

Create an APPLICATION FIELD object for displaying with GUI reader

DCAPPFIELD is an adaption of the Xbase Application Parts command APPFIELD in the DCDIALOG Getlist system. <br><br> The DCAPPFIELD command is used to configure the display of single fields in Application Parts in greater detail, compared to the available options of the DCAPPEDIT or DCAPPBROWSE command. In addition, DCAPPFIELD allows to define an expression, rather than a field, whose result is displayed in an Application Part. This is coded as an assignment, where the inline assignment operator must be used to assign the result of an expression to a memory variable. <br><br> The DCAPPFIELD command can only be used after a command that creates an Application part. For example, the command DCAPPEDIT or DCAPPBROWSE must be executed in a program (added to the GetList array) before DCAPPFIELD may be used (added to the GetList array).

Syntax:

 DCAPPFIELD <cFieldName> | <memvar> := <expression> ;
   [ INTO   <oApp>  ] ;
   [ TYPE   <cType> ] ;
   [ LEN    <nLen>  ] ;
   [ DEC    <nDec>  ] ;
   [ FONT   <cFontCompoundName> ] ;
   [ COLOR  <nForeGround1> [, <nBackGround1>] ] ;
   [ HILITE <nForeGround2> [, <nBackGround2>] ] ;
   [ ALIGN LEFT | CENTER | RIGHT ] ;
   [ WIDTH  <nWidth> ] ;
   [ READONLY ] ;
   [ HEADING | CAPTION <cHeading>    ;
     [ FONT  <cFontCompoundName> ] ;
     [ COLOR <nForeGround> [, <nBackGround>] ] ;

     [ ALIGN LEFT | CENTER | RIGHT> ] ;
   ] ;
   [ FOOTING | COMMENT <cFooting>   ;
     [ FONT  <cFontCompoundName> ] ;
     [ COLOR <nForeGround> [, <nBackGround>] ] ;
     [ ALIGN LEFT | CENTER | RIGHT ] ;
   [ GROUP <cGroup> ]

Arguments:

<cFieldName>

  <cFieldName> is a literal field name or a character expression in
  parentheses. It defines the database field to be displayed next
  in an Application Part.

<memvar> := <expression>

  If an Application Part is to display not a field but the result
  of an expression, an assignment must be specified, instead of a
  field name. The assignment must be coded using the inline
  assignment operator (:=). An expression is to be assigned to a
  memory variable (LOCAL, STATIC, PRIVATE oder PUBLIC).  <memvar>
  is the name for this variable and the result of <expression> is
  assigned to it, each time the record pointer is moved.

INTO <oApp>

  <oApp> is the name of the memory variable that references an
  Application Part. It defaults to appObject (refer to the INTO
  clause of DCAPPEDIT or DCAPPBROWSE).

TYPE <cType>

  <cType> is an upper case letter that optionally specifies the
  data type of the field <cFieldName> .

LEN <nLen>

  <nLen> is a numeric value that optionally specifies the length of
  the field <cFieldName> .

DEC <nDec>

  <nDec> is a numeric value that optionally specifies the number of
  decimal places of the field <cFieldName> .

FONT <cFontCompoundName>

  The FONT clause optionally specifies a character string defining
  the compound name of the font to be used for displaying a field
  (see also the  :setFontCompoundName() method of Xbase Parts).

COLOR <nForeGround1> [, <nBackGround1>]

  The COLOR option specifies foreground and background color for
  the display of a single field. #define constants from XBP.CH or
  GRA.CH must be used (XBPSYSCLR_* or GRA_CLR_*).

HILITE <nForeGround2> [, <nBackGround2>]

  The option HILITE defines foreground and background color for
  hilighted display of a field. This option is used differently in
  different Application Parts. For APPBROWSE it defines the color
  of the cell cursor, while APPEDIT uses it as color to mark text
  in an entry field.

ALIGN  LEFT | CENTER | RIGHT

  The option ALIGN defines alignment of displayed data: left,
  center or right.

WIDTH <nWidth>

  <nWidth> defines the width of a field for display. It is a
  numeric value and corresponds to "number of characters". The
  width is calculated from the expression Replicate("W",<nWidth>),
  because W is the widest character in a proportional font.

READONLY

  The option READONLY suppresses the possibility to edit a field.
  READONLY is always set when DCAPPFIELD is not used with a field
  name, but with an assignment (<memvar> := <expression>).

HEADING | CAPTION <cHeading> [ <Options> ]

  <cHeading> is a character string that is displayed as column
  heading with DCAPPBROWSE, and as caption of an entry field with
  DCAPPEDIT. The key words COLOR, FONT and ALIGN can be used for
  <Options> . This allows to define color, font and alignment for
  a single column heading or caption.

FOOTING | COMMENT <cFooting> [ <Options> ]

  <cFooting> is a character string that is displayed as column
  footing with DCAPPBROWSE, and as message in the status line with
  APPEDIT. The key words COLOR, FONT and ALIGN can be used for
  <Options> . This allows to define color, font and alignment for
  a single column heading or message.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
 this GetList object.  Assignment to a group makes it possible to
 perform operations only on GetList items which are members of a
 specified group, using functions such as DC_GetRefresh() or
 DC_ReadGui().

Examples:

 #include "dcapp.ch"

 PROCEDURE Xtest()

 LOCAL GetList := {}, oStatic, oAppEdit

 USE COLLECT NEW SHARED

 @  0,0 DCSTATIC XBPSTATIC_TYPE_RAISEDBOX SIZE 78,18.5 ;
    GROUP oStatic

 DCAPPEDIT INTO oAppEdit STYLE 3D POSITION 0,0 PARENT oStatic

 DCAPPFIELD COLLECT->descrip INTO oAppEdit ;
   CAPTION 'Description' ;
   COLOR GRA_CLR_BLUE

 DCAPPFIELD COLLECT->type INTO oAppEdit  ;
   CAPTION 'Type'       ;
   COLOR GRA_CLR_BLUE

 DCAPPFIELD COLLECT->sub_type INTO oAppEdit  ;
   CAPTION 'Sub-Type' ;
   COLOR GRA_CLR_BLUE

 DCAPPFIELD COLLECT->location INTO oAppEdit  ;
   CAPTION 'Location' ;
   COLOR GRA_CLR_BLUE

 DCAPPFIELD COLLECT->date_orig INTO oAppEdit  ;
   CAPTION 'Date of Origin' ;
   COLOR GRA_CLR_BLUE

 DCAPPFIELD COLLECT->date_acqu INTO oAppEdit  ;
   CAPTION 'Acquired Date' ;
   COLOR GRA_CLR_BLUE

 DCAPPFIELD COLLECT->appr_value INTO oAppEdit  ;
   CAPTION 'Appraised Value' ;
   COLOR GRA_CLR_BLUE

 DCAPPFIELD COLLECT->for_sale INTO oAppEdit  ;
   CAPTION 'For Sale?' ;
   COLOR GRA_CLR_BLUE

 DCAPPFIELD COLLECT->condition INTO oAppEdit  ;
   CAPTION 'Condition' ;
   COLOR GRA_CLR_BLUE

 DCAPPFIELD COLLECT->bitmap1 INTO oAppEdit  ;
   CAPTION 'Bit Map File #1' ;
   COLOR GRA_CLR_BLUE

 DCAPPFIELD COLLECT->bitmap2 INTO oAppEdit  ;
   CAPTION 'Bit Map File #2' ;
   COLOR GRA_CLR_BLUE

 DCAPPFIELD COLLECT->comments INTO oAppEdit  ;
   CAPTION 'Comments' ;
   COLOR GRA_CLR_BLUE

 DCAPPFIELD COLLECT->memo INTO oAppEdit  ;
   CAPTION 'How was this item acquired?' ;
   COLOR GRA_CLR_BLUE ;
   WIDTH 60

 DCREAD GUI ;
   FIT ;
   ADDBUTTONS

 RETURN

Files:

DCAPP.CH

See Also:

   DCREAD GUI
   dc_readgui()


DCBDEBUG

Send debug information to a browse-style debugging window

DCBDEBUG or DD is used to send data to a browse-style debugging window when debugging GUI applications. <br><br> A list of expressions may be included and the output of each expression will be displayed in a new row in the browse window.<br><br> This is a major improvement over DCQDEBUG because it uses an array browse rather than a memo to show debug information. Improvements: a. Updating the window is much faster therefore does not slow down application.<br><br> b. Data is in resizeable and moveable columns<br><br> c. Each debug line may have its own color.<br><br> d. Supports multiple windows.<br><br> e. Double-Clicking on debug item in window displays more info about that item, such as array browsing, object inspecting, etc.<br><br> f. Information doesn't scroll off the window. No limit to amount of debugging information.<br><br> g. Double-clicking the heading of a column will optimize the width of that column to display all data.<br><br> h. Double-clicking the data area of a column will cause the editor to go to the associated line of code in the source file. <br><br> <br><br>

Syntax:

 DCBDEBUG <xExpr1> [ ; <xExprN> ] ;
          [WINDOW <nWindow>] ;
          [COLOR <nbFgColor> [,<nBgColor>] ;
          [PAUSE <bPause>] ;
          [PAUSE] ;
          [ALWAYSONTOP] ;
          [WHEN <bWhen>]

Arguments:

<xExpr1> through <xExprN> is any expression.

WINDOW <nWindow> is the debug window to send the information.
If this clause is not used then the information is sent to debug
window # 1.

COLOR <nbFgColor> and <nBgColor> are the foreground and background
colors of the information to display in the window.  If <nbFgColor>
is a code block, then <nBgColor> is ignored.  The code block must
return an array of two numeric elements, ie a foreground color
and a background color.

PAUSE will cause the program execution to stop until the "Continue"
button on the debug window is activated.

PAUSE <bPause> will cause the program execution to stop only if
<bPause> evaluates as .TRUE.

ALWAYSONTOP will force the debug window to always display in
front of all other windows.

WHEN <bWhen> is a codeblock that will cause the debug info to be
displayed only when the codeblock returns .t.
Ex: DCBDEBUG i, oInfo WHEN {||i==16}

Notes:

A shortened command: DD Use this as a replacement for DCBDEBUG.

DC_DebugQoutAppendBlock() is a get-set function used to setupadditional information to append to each debug line.

Examples:

 #include "dcdialog.ch"

 USE COLLECT NEW SHARED

 DCBDEBUG Alias(), RecCount()
 DCBDEBUG RecNo() WINDOW 2 COLOR GRA_CLR_RED

Files:

DCDIALOG.CH

See Also:

   dc_debugbrowse()
   DCQDEBUG
   DCLDEBUG
   WTF


DCBITMAP

Create a BITMAP object for displaying with the GUI reader

The command DCBITMAP creates a new BitMap object and adds the object to the array named GETLIST which is later processed by the DC_READGETS() function or by the DCREAD command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> The GetList is passed to the function DC_READGETS() which looks at the DC_GUI() flag and determines whether to process this list as a standard text-based get screen or as a GUI-based dialogue.<br><br> A DCBITMAP object is drawn into the presentation space of a parent DCSTATIC object. This command is used to draw bitmaps like .BMP files, .JPG files and resources that have been linked in the .EXE.<br><br> DCBITMAP objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCRADIO, @..DCPUSHBUTTON or @..DCMULTILINE.

Syntax:

DCBITMAP <ncoRes> ;
    [PARENT <oParent>] ;
    [PARENTID <cParentId>] ;
    [TARGETRECT <nTgtSrow>,<nTgtScol>,<nTgtErow>,<nTgtEcol>] ;
    [SOURCERECT <nSrcSRow>,<nSrcSCol>,<nSrcERow>,<nSrcECol>] ;
    [BITS <nB>] ;
    [PLANES <nP>] ;
    [OBJECT <oObject>] ;
    [CARGO <xCargo>] ;
    [AUTOSCALE] ;
    [CENTER] ;
    [PREEVAL <bPreEval>] ;
    [EVAL <bEval>] ;
    [ID <cId>] ;
    [TITLE <cTitle>] ;
    [GROUP <cGroup>] ;
    [SUBCLASS <cSubClass>]

Arguments:

TARGETRECT <nTgtSRow>,<nTgtSCol>,<nTgtERow>,<nTgtECol> identifies
the TARGET rectangular area in the presentation space where the
bitmap is displayed.  If they are not included, the output area
is the same size as the area of SOURCERECT.

SOURCERECT <nSrcSRow>,<nSrcSCol>,<nSrcERow>,<nSrcECol> specifies
a rectangular area of the bitmap that is displayed in the
presentation space.  The coordinates must always be specified in
pixels and are device dependent.  The default value for SOURCERECT
aSourceRect> is {0, 0, oBitmap:xSize, oBitmap:ySize} which is the
entire bitmap.

<ncoRes> is the value of the bitmap.  This may be one of the
following types:

(N)umeric - A resource that is linked to the .EXE

(C)haracter - The name of a .BMP file to load or the name of a
.JPG (JPEG) file to load. It must not be a macro unless <ncoRes>
is a codeblock.

(O)bject - A bitmap object derived from the XbpBitmap() class.

The <ncoRes> is automatically anchored via a Get-Set codeblock
created by DC_GetAnchorCB() unless <ncoRes> is a custom Get-Set
code block.

PARENT <oParent> is the name of the variable that was
assigned to the parent STATIC object for this BitMap Object.
Only  use this command if you are placing this Browse onto
another dialogue object.  If this clause is not used, then the
BitMap will be displayed in the top-level dialogue screen.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

BITS <nB> contains the number of bits that are used for color
coding in the bitmap.  This value is generally 8 for a color
bitmap and 1 for a black and white bitmap.

PLANES <nP> contains the number of bit planes (color levels) that
are used to code pixels in the raster image.  Generally the value
is 1.  For a true color bitmap, the value is 3, meaning that a
screen dot is formed by 3x8 = 24 bits.

OBJECT <oObject> is local variable name to store a reference
to this object after it is created.

AUTOSCALE will automatically scale the BitMap to fit the
presentation space of the parent object using the same aspect
ratio as the original bitmap.  If this option is not used, then
the bitmap with fill the entire area of the presentation space.

CENTER will center the bitmap in the presentation of the parent
object.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

SUBCLASS <cSubClass> is a string containing a class name that
will be used to create the class, rather than DC_XbpBitMap().
This class should inherit from DC_XbpBitMap().
See the example in \exp19\samples\subclass.

Examples:

#include 'dcdialog.ch'
#include 'appevent.ch'

PROCEDURE Xtest()

LOCAL GetList := {}, oClipPhoto, oBitMap, cBitMap, lPlayBack

@  4,10 DCSTATIC XBPSTATIC_TYPE_RAISEDBOX SIZE 50,10 ;
   GROUP oClipPhoto

cBitMap := ''
DCBITMAP cBitMap PARENT oClipPhoto AUTOSCALE OBJECT oBitMap

lPlayBack := .f.

@ 4,65 DCPUSHBUTTON CAPTION 'PlayBack' SIZE 9,2 ;
       TOOLTIP 'Play Back all BitMaps in IMAGES.DBF' ;
       ACTION {||lPlayBack := .t., ;
                 DisplayImages(oClipPhoto,oBitMap,@lPlayBack) }

@ 7,65 DCPUSHBUTTON CAPTION 'Stop' SIZE 9,2 ;
       TOOLTIP 'Stop the Play Back' ;
       ACTION {||lPlayBack := .f.}

DCREAD GUI FIT ADDBUTTONS TITLE 'BitMap Demo'

RETURN

/* ------------------- */

STATIC PROCEDURE DisplayImages( oClipPhoto, oBitMap, lPlayBack )

LOCAL nSeconds, lClearBox := .t., nSaveArea := Select(), cBmpDb, ;
      nEvent, oXbp, mp1, mp2, cAlaskaDrive

IF !lPlayBack
  RETURN
ENDIF

cBmpDb := 'C:\ALASKA\XPPW32\SOURCE\SAMPLES\DATA\BMPDB.DBF'
IF !File(cBmpDb)
  cAlaskaDrive := SubStr(GetEnv('XPPRESOURCE'),1,2)
  cBmpDb := Strtran(cBmpDb,'C:',cAlaskaDrive)
ENDIF
IF File(cBmpDb)
  IF !DC_DbSel('BMPDB')
    USE (cBmpDb) NEW VIA foxcdx
  ENDIF
  nEvent := xbeP_None
  DO WHILE lPlayBack .AND. nEvent # xbeP_Close
    oBitMap:setBuffer(FIELD->BITMAP,XBPBMP_FORMAT_WIN3X)
    DC_BitMapDraw( oClipPhoto, oBitMap, lClearBox )
    lClearBox := .f.
    IF Eof()
      DbGoTop()
    ELSE
      DbSkip(1)
    ENDIF
    Sleep(0.1)
    nEvent := AppEvent( @mp1, @mp2, @oXbp, .01 )
    IF Valtype(oXbp) = 'O'
      oXbp:handleEvent( nEvent, mp1, mp2, oXbp )
    ENDIF
  ENDDO
  CLOSE
ENDIF

RETURN

Files:

DCDIALOG.CH


DCBROWSECOL

Create a BROWSE column object for displaying with GUI reader

The command DCBROWSECOL creates a new Browse column definition and adds it to the array named GETLIST which is later processed by the DC_Read*() functions or by the DCREAD * commands. The GETLIST array must be first declared and initialized to the value of {}. <br><br> The command DCREAD GUI creates the DC_Xbp*() objects and activates the edit mode for all definitions found in the GetList array.<br><br> The command DCREAD HTML creates the DC_Html*() objects and writes the HTML source code.<br><br> A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> A DCBROWSECOL object can only be added to a DCBROWSE object or a DCQUICKBROWSE object (the parent) which must be created first. <br><br>NAME <cVarName> is the variable name to assign to the GET object (for HTML based applications.)

Syntax:

DCBROWSECOL ;
    [DATA <bData>] ;
    [FIELD <xField>] ;
    [ELEMENT <nElement>] ;
    [HEADER <cHeader> [HCOLOR <bncHFgC> [,<ncHBgC>]]] ;
  * [HEADPRES <aHeadPres>] ;
  * [WIDTH <nWidth> [PIXEL] ] ;
    [PICTURE <bcPicture>] ;
    [FOOTER <cFooter>] ;
  * [FOOTPRES <aFootPres>] ;
  * [TYPE <nType>] ;
    [COLOR <bncFgC> [,<ncBgC>] ] ;
    [FONT <bocFont>] ;
    [PARENT <oParent>] ;
    [PARENTID <cParentId>] ;
    [TOOLTIP <bcToolTip>] ;
    [MESSAGE <bcMsg> [INTO <oMsgBox>]] ;
    [HELPCODE <cHelpCode>] ;
    [OBJECT <oObject>] ;
    [CARGO <xCargo>] ;
  * [PRESENTATION <aPres>] ;
  * [VALID <bValid> [ALWAYS]] ;
    [WHEN <bWhen>] ;
    [HIDE <bHide>] ;
  * [PROTECT <bProtect>] ;
    [PREEVAL <bPreEval>] ;
    [EVAL <bEval>] ;
    [SORT <bSort> [LEFTBUTTON] [DEFAULT] ] ;
    [ID <cId>] ;
    [TITLE <cTitle>] ;
  * [ACCELKEY <anAccel>] ;
  * [GOTFOCUS <bGotFocus>] ;
  * [LOSTFOCUS <bLostFocus>] ;
  * [VISIBLE] ;
  * [INVISIBLE] ;
    [GROUP <cGroup>] ;
  * [EDITOR <bcEditor> [EXITKEY <nExitKey>]] ;
  * [TYPE <anType>] ;
  * [REPRESENTATION <aRep>] ;
    [ALIGN <nAlign>] ;
  * [DATATOOLTIP <bToolEnable> [TIPBLOCK <bTipBlock>] ] ;
  * [DRAG <bDrag> [DIALOG <bDD>] ;
  * [DROP <bDrop> [CURSOR <nDropCursor>] ;
  * [SUBCLASS <cSubClass>] ;
  * [OBJECTVAR <bcObjectVarName> [ELEMENT <nObjectElement>]] ;
  * [OWNERDRAW]

Arguments:

DATA <abData> is a or an array of code blocks code block to evaluate.
If browsing an array use a code block like so:

 {||DC_GetColArray(<nArrayElement>,<oBrowse>)} ****

If browsing a database use a code block like so:

 {||CUSTOMER->cust_name}

If Multi-Row browsing is desired, use an array of code blocks
like so:

 { {||'Size: ' + Alltrim(Str(DC_GetColArray(2,oBrowse)))}, ;
                {||'Date: ' + DtoC(DC_GetColArray(3,oBrowse))}, ;
                {||'Time: ' + DC_GetColArray(4,oBrowse)} }

  NOTE: Multirow browsing causes the data in each code block to
        be displayed on a separate line within the row of the
        browse.  This requires using presentation parameters
        to increase the height of each row.  See the sample
        MULTIROW.PRG sample in SAMPLES\BROWSE.

- or -

FIELD <cField> is the name of a database field to browse.
Use this clause only with databases instead of the DATA <bData>
clause.  The field clause will create a GET/SET style codeblock
which is needed when using the cell-editing feature with the
EDIT clause of the @ DCBROWSE command.  The cell editor handles
handles record locking and unlocking.

- or -

ELEMENT <nElement> is the element number of a multi-dimensional
array.  Use this clause only with arrays instead of the DATA <bData>
clause.

<oBrowse> is the name of the variable to assign as a storage
place for this object.

WIDTH <nWidth> is the width of the column in characters unless
the PIXEL clause is used thus making the column width in pixels.
Note: If a proportional font is used (ie. Arial) and the PIXEL
clause is not used, the width of the column will not be the
same as the number of characters displayed.

HEADER <bcHeader> is the heading of the column.  If the parent
is a DCBROWSE object, this may be a multiple-line header if
the HEADLINES <nLines> clause of the parent @ DCBROWSE command
is used. If <bcHeader> is a code block, it must return a character
string. A code block header is reevaluated every time the ::refresh()
method of the parent DC_XbpBrowse() object is called.  It is also
reevaluted by calling DC_GetRefresh(GetList).

HCOLOR <bncHFGc>, <ncHBGc> are foreground and background colors of
the header. They may be character strings representing valid
text-based colors supported by SetColor() or they may be numeric
constants which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH. If <bncFGc> is a code
block is must return a 2-element array containing a foreground
and background color. The array may also consist of two sub-arrays
containing RGB colors. ****

HEADPRES <aHeadPres> is a two-dimensional array. If specified,
this contains presentation parameters for the Header object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the header and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.  If no PRESENTATION clause is used, then the default
is the PRESENTATION parameters of the parent Browse object. ****

FOOTER <cFooter> is an optional footer for the column. This may be
a multiple-line footer if the FOOTLINES <nLines> clause of the
parent @ DCBROWSE command is used. ****

FOOTPRES <aFootPres> is a two-dimensional array. If specified,
this contains presentation parameters for the Footer object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the header and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.  If no PRESENTATION clause is used, then the default
is the PRESENTATION parameters of the parent Browse object. ****

PICTURE <cPicture> is any valid picture clause which will modify
the presentation of the data via the Transform() function.  ****

PARENT <oParent> is the name of the variable that was assigned to
the parent browse object previously created by the @ DCBROWSE
command or the @ DCQUICKBROWSE command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

FONT <cFont> is a character string defining an optional font.
The font string must conform to the Xbase++ standard, ie.
"10.Courier Bold". It may also be a font object or a code block
that returns a character string or a font object to later
refresh with DC_GetRefresh().

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the Column object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.  If no PRESENTATION clause is used, then the default
is the PRESENTATION parameters of the parent Browse object. ****

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

VALID <bValid> is a code block to be evaluated for validating
the data-entered when cell-editing in the browse.  The code
block is only used when cell-editing is enabled with the EDIT
clause of the @ DCBROWSE command and cell editor object does not
have its own VALID clause.  The code block must return a
logical value.  The edit buffer is passed to the code block,
therefore the codeblock should like like so:

 { |c| !Empty(c) }

If the cell editor object has it's own valid clause then the
VALID clause will be ignored and the editor object is passed to
the editor's code block.  The ALWAYS sub-clause will cause the
code block to be evaluated always when cell editing rather than
just when the value changes.

MESSAGE <bcMsg> is the message you want to display in the
message area of the dialogue screen defined by the DCMESSAGEBOX
command when the object is in focus.  Optionally, INTO <oMsgBox>
will designate which message box to display the message into.
If the INTO clause is not used, then the last message box in the
GetList is the default. If <bcMsg> is a code-block, it must
return a character string.  <oMsgBox> may also be any object that
supports the :setCaption() method. ****

HELPCODE <cHelp> is a character string that is passed to the
DC_HelpF1() function if F1 is pressed or the HELP button
is clicked when this GET has focus.  This HELPCODE allows
the Help system to override the passing of the Procedure and
Varname for more specific context-help.

OBJECT <oObject> is the name of a variable to use as a container
for the XbpColumn object.

TOOLTIP <bcToolTip> is a character string which will display
as a "Tool Tip" next to the object when the cursor is passed
over the object. A semi-colon within the text indicates a new
line.  If <bcToolTip> is a code-block, it must return a character
string.  NOTE: The Tooltip painting method is run in another
thread, therefore the codeblock should not run code that points
to the current work area.  It may however, contain local, public
or private variables. ****

WHEN <bWhen> is a code block to be evaluated before setting focus
to this column.  The code block must return a logical value.  If
the code block returns a .FALSE. the cell cannot be highlighted
or resized. ****

HIDE <bHide> is a code block to be evaluated to hide this column.
The code block must return a logical value.  If the code block
returns a .FALSE. the column will be displayed, otherwise it will
be hidden.  The code block is evaluated by DC_GetRefresh().

PROTECT <bProtect> is a code block to be evaluated before cell-
editing in the browse.  The code block must return a logical value.
If the code block returns a .TRUE. the cell cannot be edited.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader..

COLOR <bncFGc>, <ncBGc> are foreground and background colors.
They may be character strings representing valid text-based
colors supported by SetColor() or they may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH. If <bncFGc> is a
code block is must return a 2-element array containing a
foreground and background color. ****

SORT <bSort> is an optional code block to evaluate for sorting
the browse when the mouse right button is clicked in the header
area of a column.  ****  Usage of the code block is as follows:

{ | aPos, nColPos, self | ... }

<aPos> is a two-element array containing the mouse coordinates.
<nColPos> is the column number of the browse column.  <self> is
the Column object.  LEFTBUTTON is an optional clause that enables
the use of the LEFT mouse button in the header, otherwise only
the RIGHT button is enabled.  The left button is disabled by
default to prevent conflict with column sizing.

DEFAULT will establish this column as the default sorted column,
as though the mouse was clicked in the header.  This clause
should be used only if the sort order established by the sort
block is equal to the current sort order.

NOTE: The heading colors and bitmaps for the sorted columns may
      be established by the SORT* clauses of the @ DCBROWSE
      command.  The value returned by the code block determines
      whether or not the column header is highlighted.  If the
      value is a .FALSE., then the header is not highlighted.
      Any other value will cause the header to be highlighted.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

ACCELKEY <anAccel> is a numeric "hot-key" assignment that will set
focus to the checkbox object when the hot-key is pressed.  The key
must be a valid key with the prefix xbeK_*.  These keys are
defined in APPEVENT.CH.  <anAccel> may also be an array of numeric
values to assign more than one key to the object. ****

GOTFOCUS <bGotFocus> is a code block that is evaluated when this
object receives input focus.  <bGotFocus> := {|uNIL1,uNIL2,self|...}
****

LOSTFOCUS <bLostFocus> is a code block that is evaluated when this
object loses input focus.   <bLostFocus> := {|uNIL1,uNIL2,self|...}
****

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS
****

EDITOR <bcEditor> may be the character string ID of the object
in the GetList which will be used as the Cell-Editor for this
column or a code-block.  Cell-editing is enabled via the EDIT
clause of the DCBROWSE command which created the parent object for
this column.  If the EDITOR clause is not used then the cell-editor
is a standard DCGET.  Any existing object such as a DCGET,
DCMULTILINE, DCCOMBOBOX, etc. may be used as the cell editor,
however it must have been assigned an ID.  All properties of the
cell editor are used as they were defined by it's respective command
with the exception of the width, which is determined by the width of
the cell.  If <bcEditor> is a codeblock, the codeblock will be
evaluated when the edit mode is invoked.

CELL EDITING NOTE 1: When using a DC* command to create an object
which will be used only as a cell editor and not displayed in
the dialog, <nRow> and <nCol> coordinates must be entered as NIL
and no parent clause is required. If the DC* command being used
as the cell editor is a Getlist object that is also painted on a
dialog screen with <nRow> and <nCol> coordinates, the SIZE must
be in PIXELS.

CELL EDITING NOTE 2: EXITKEY <nExitKey> is the key to use to exit
the editing within the cell and move to the next cell.  The
default is xbeK_ENTER.  When editing a cell with a DCMULTILINE
object it is recommended that <nExitKey> be a key such as
xbeK_END or xbeK_F10.

CELL EDITING NOTE 3: The variable associated with the EDITOR
object may be any Get/Set code block or a variable initialized
to a NIL value.  When it is a NIL, then the Get/Set code block
attached to the browse column will be used.  A NIL variable is
recommended for ease of programming.

TYPE <anType> is an array defining the type of each column.
{ <cValtype>, <nDisplayType>, <cPicture> }.

<cValType> is the type of data displayed in the column. It is
specified using a letter equivalent to the return value of the
Valtype() function. These are usually the characters "C", "D",
"L" or "N".

<nDisplayType> defines the display type of the column, or how
data is visualized. Data can be represented in textual (default)
or graphic form. Constants defined in XBP.CH are used for
<nDisplayType> . They are listed in the table below:

Constants used for <nDisplayType>

 Constant                  Description

 XBPCOL_TYPE_BITMAP        The column displays bitmaps
 XBPCOL_TYPE_ICON          The column displays icons
 XBPCOL_TYPE_SYSICON       The column displays system-icons
 XBPCOL_TYPE_FILEICON      The column displays normal file-icons
 XBPCOL_TYPE_FILEMINIICON  The column displays small file-icons
 XBPCOL_TYPE_TEXT      *)  The column displays textual data

 *) default value

<bcPicture> optionally defines a picture string for textual data.
Refer to the Transform() function for picture formatting rules.
If this is a code block, then the code block must return a
character string.

REPRESENTATION <aRep> is an array of information about the
presentation of column. ####  The array looks like this:

 { <xValue>, <nNormalID>, <nHiliteID> }

  When data in a column cell has the value <xValue>  the image
  with the resource ID <nNormalID> is displayed in the cell. If
  the cell is to be hilited, the image with the ID <nHiliteID> is
  displayed. The value -1 is valid for both resource IDs. In this
  case, nothing is displayed in the cell. Once a visual
  representation is defined, it can be voided by specifying NIL
  for the resource IDs.

ALIGN <nAlign> is a numeric value that defines horizontal and
vertical alignment ####:

 Constants for alignment

 Constant          Description

 XBPALIGN_TOP      Alignment at the top
 XBPALIGN_LEFT     Alignment on the left
 XBPALIGN_BOTTOM   Alignment at the bottom
 XBPALIGN_RIGHT    Alignment on the right
 XBPALIGN_HCENTER  Horizontally centered
 XBPALIGN_VCENTER  Vertically centered

DATATOOLTIP <bToolEnable> is a code block that is evaluated in
the tooltip thread when the mouse is passed over the data area
of a browse column.  If <bEnable> returns a .TRUE. the contents
of the cell are displayed in a tooltip.  Use this clause when
browse columns are shorter than the data in the cell. Semicolon (;)
characters or CRLF (Chr(13)+Chr(10)) pairs in the cell are
interpreted as a line break. If <bTipBlock> is a code block then
the return value of the code block will be displayed as the
tooltip.  The code block may return a text string or a pointer
to an XbpBitMap() object.  If browsing a database, then the
record pointer will be set to the same record as the cell
requesting the tip.  If browsing an array, then the row element
number of the cell requesting the tip will be passed to the code
block.

DRAG <bDrag> is a codeblock to evaluate when the left mouse button
is clicked in the object and the drag is started.  The return
value of the code block will be stored in memory to be later
retrieved by the Drop operation. A pointer to the clicked on
object is passed to the code block.

DIALOG <bDD> is a codeblock that will evaluate when the drag is
started.  This is used to call a function that will create a
dialog window which will move with the mouse during the drag.
The dialog window will be destroyed upon the drop operation
or the release of the mouse.

Ex: DRAG {|o|o:getData()} DIALOG {|mp1,mp2,oXbp|DragDialog(mp1,mp2,oXbp)} ;

DROP <bDrop> is a codeblock to evaluate when the left mouse button
is released in the object and the drag is ended.  A pointer to
the object and the value stored in memory at the start of the
Drag are passed to the code block.

CURSOR <nDropCursor> is the mouse cursor that will show when it
is moved over this object during a drag operation.

Ex: DROP {|o,x|o:setData(x),o:invalidateRect()} ;
       CURSOR POINTER_DATADROP_ASSIGN

SUBCLASS <cSubClass> is a string containing a class name that
will be used to create the class, rather than DC_XbpColumn().
This class should inherit from DC_XbpColumn().
See the example in \exp19\samples\subclass.

OBJECTVAR <bcObjectVarName> is the name of an iVar in an object
that exists in the array being browsed.  If <bcObjectVarName> is
a code block, then the object is passed as the first parameter to
the code block.  ELEMENT <nObjectVarElement> is required if the
object column is in a multi-dimensional array.  If a single-dimensional
array of objects is being browsed, then the ELEMENT clause is not used.
To see how to use the OBJECTVAR clause look at the sample
in .\samples\browse\objects.prg.

OWNERDRAW provides the ownerdraw capability to the browse system.
See the example in .\samples\browse\ownerdraw.prg.  Columns that
do not use the ownerdraw clause will be drawn by the default draw
system, otherwise they will be drawn by the custom draw system.

Notes:

Clauses marked with an asterisk ( * ) are not supported by DCREAD HTML.

Text that includes a **** denotes that this feature is supported only when the parent object is a DCBROWSE (XbpBrowse) object.

Text that includes a #### denotes that this feature is supported only when the parent object is a DCQUICKBROWSE (XbpQuickBrowse) object.

GUI applications:

When using a DCBROWSE object (DC_XbpBrowse) as the parent for DCBROWSECOL, a DC_XbpColumn object is created and added to the childlist of the DC_XbpBrowse parent.

When using a DCQUICKBROWSE object (DC_XbpQuickBrowse) as the parent for a DCBROWSECOL, there is no child object created, instead the DCBROWECOL command creates a psuedo-object of the DC_QBColumn() class for use with cell-editing. These column objects are not children of the DC_XbpQuickBrowse class but instead are added to an array that is stored in the parent's :cargo slot.

----------------------

HTML applications:

A column object of the DC_HtmlColumn() class is created and added to the childlist of the DC_HtmlBrowse() class.

Examples:

 /*
 This example demonstrates both a database browse and an
 array browse in the same dialogue screen.  The database
 browse is on Tab Page 1 and the Array browse (directory
 listing) is on Tab Page 2.
 */

 #include "dcdialog.ch"
 #include "xbp.ch"

 PROCEDURE Xtest()

 LOCAL GetList := {}, GetOptions, oTabPage1, oTabPage2, ;
       oBrowse, cAlias, aDirectory, oDirectory

 USE COLLECT NEW SHARED

 /* ---- Tab Page #1 ---- */

 @ 3,3 DCTABPAGE oTabPage1 CAPTION 'Browse' ;
   SIZE 60,12

 cAlias := "BASEBALL"

 @ 2,2 DCBROWSE oBrowse PARENT oTabPage1  ;
       DATA cAlias SIZE 55,9 FREEZELEFT { 1, 2 }

 DCBROWSECOL FIELD COLLECT->descrip ;
   HEADER "Description" PARENT oBrowse

 DCBROWSECOL FIELD COLLECT->type ;
   HEADER "Type" PARENT oBrowse

 DCBROWSECOL FIELD COLLECT->sub_type ;
   HEADER "SubType" PARENT oBrowse

 DCBROWSECOL FIELD COLLECT->location ;
   HEADER "Location" PARENT oBrowse

 DCBROWSECOL DATA {|a|a:={'Yes','No','Not Sure'},a[COLLECT->for_sale+1]} ;
   HEADER "For Sale?" PARENT oBrowse

 DCBROWSECOL FIELD COLLECT->date_orig ;
   HEADER "Orig Date" PARENT oBrowse

 DCBROWSECOL FIELD COLLECT->date_acqu ;
   HEADER "Acqu Date" PARENT oBrowse

 DCBROWSECOL FIELD COLLECT->orig_price ;
   HEADER "Acqu Price" PARENT oBrowse

 DCBROWSECOL FIELD COLLECT->appr_value ;
   HEADER "Appr Value" PARENT oBrowse

 DCBROWSECOL FIELD COLLECT->condition ;
   HEADER "Condition" PARENT oBrowse

 DCBROWSECOL DATA {||IIF(COLLECT->original,'Yes','No')} ;
   HEADER "Orig Owner?" PARENT oBrowse

 /* ---- Tab Page #2 ---- */

 @  0,0 DCTABPAGE oTabPage2 CAPTION 'Directory' ;
    RELATIVE oTabPage1

 aDirectory := Directory()

 @ 2,2 DCBROWSE oDirectory PARENT oTabPage2 ;
       DATA aDirectory SIZE 55,9

 DCBROWSECOL ELEMENT 1 HEADER "Name" PARENT oDirectory WIDTH 10

 DCBROWSECOL ELEMENT 2 HEADER "Size" PARENT oDirectory WIDTH 8

 DCBROWSECOL ELEMENT 3 HEADER "Date" PARENT oDirectory WIDTH 8

 DCBROWSECOL ELEMENT 4 HEADER "Time" PARENT oDirectory WIDTH 8

 DCREAD GUI ;
   TITLE "My COLLECTION" ;
   FIT ;
   ADDBUTTONS ;
   EVAL {||oBrowse:hide(), oBrowse:show()}

 RETURN

/*
This is an example of an array editor which
uses custom EDITORs for cell-editing.
*/

FUNCTION XSample_49()

LOCAL oBrowse, oBrowBox, aStructure, aFields, GetList := {}, ;
      oToolBar, GetOptions, aOldStruct, lOk, oColumn1, nPointer, ;
      aField, xNIL := NIL

USE collect VIA 'DBFNTX'
aStructure := dbstruct()
aOldStruct := AClone(aStructure)
aFields := ARRAY(LEN(aStructure))
aFields := aStructure[1]

FOR nPointer := 1 TO Len(aStructure)
   aStructure[nPointer,1] := Pad(aStructure[nPointer,1],10)
NEXT
nPointer := 1

@  2,2 DCSTATIC XBPSTATIC_TYPE_RECESSEDBOX SIZE 45,12 ;
        OBJECT oBrowBox

@ .1,.5 DCBROWSE oBrowse DATA aStructure PARENT oBrowBox;
        SIZE 43,11.8 EDIT xbeBRW_ItemSelected ;
        INTO aField ;
        POINTER nPointer ;
        DELETE xbeK_DEL ;
        INSERT xbeK_INS

DCBROWSECOL ELEMENT 1 WIDTH 8 HEADER "Name" PARENT oBrowse ;
   OBJECT oColumn1 ;
   EDITOR 'NAME'

DCBROWSECOL ELEMENT 2 WIDTH 5 HEADER "Type" PARENT oBrowse ;
   EDITOR 'TYPE' // VALID {|c|_XSample49(2,c,aStructure,oBrowse)}

DCBROWSECOL ELEMENT 3 WIDTH 5 HEADER "Length" PARENT oBrowse ;
   EDITOR 'LENGTH' // VALID {|n|_XSample49(3,n,aStructure,oBrowse)}

DCBROWSECOL ELEMENT 4 WIDTH 5 HEADER "Decimals" PARENT oBrowse ;
   EDITOR 'DECIMALS' // VALID {|n|_XSample49(4,n,aStructure,oBrowse)}

@ NIL,NIL DCGET xNIL PICT "@!" GETID 'NAME'  ;
          VALID {|o|_XSample49(1,aStructure,oBrowse,nPointer)}

@ NIL,NIL DCGET xNIL PICT "!"  GETID 'TYPE' ;
          VALID {|o|_XSample49(2,aStructure,oBrowse,nPointer)}

@ NIL,NIL DCGET xNIL PICT "999" GETID 'LENGTH' ;
          VALID {|o|_XSample49(3,aStructure,oBrowse,nPointer)} ;
          WHEN {|o|_XSample49(7,aStructure,oBrowse,nPointer)}

@ NIL,NIL DCGET xNIL PICT "999"  GETID 'DECIMALS' ;
          VALID {|o|_XSample49(4,aStructure,oBrowse,nPointer)} ;
          WHEN {|o|_XSample49(8,aStructure,oBrowse,nPointer)}

@ 15,1 DCTOOLBAR oToolBar SIZE 45,1.5 BUTTONSIZE 10,1.5

DCADDBUTTON CAPTION '&Insert' PARENT oToolBar ;
   TOOLTIP 'Add New Field' ;
   ACCELKEY xbeK_ALT_I ;
   ACTION {||SetAppFocus(oColumn1),PostAppEvent(xbeK_INS,,,oBrowse)}

DCADDBUTTON CAPTION '&Delete' PARENT oToolBar ;
   TOOLTIP 'Delete Field' ;
   ACCELKEY xbeK_ALT_D ;
   ACTION {||SetAppFocus(oColumn1),PostAppEvent(xbeK_DEL,,,oBrowse)}

DCGETOPTIONS ABORTQUERY

DCREAD GUI FIT TITLE "Database Structure Editor";
   BUTTONS DCGUI_BUTTON_OK + DCGUI_BUTTON_CANCEL ;
   ARRAYTRANSLATE ;
   OPTIONS GetOptions ;
   TO lOk ;
   SETFOCUS oColumn1 ;
   EVAL {|o|SetAppWindow(o)}

RETURN IIF( lOk, aStructure, aOldStruct )

/* ------------------- */

STATIC FUNCTION _XSample49( nAction, aStructure, oBrowse, nPointer, xValue )

LOCAL nFound, GetList := {}, GetOptions, ;
      nVarLength, nNumStart, nNumEnd, nVarPointer, cNewString, ;
      cFieldName, cFieldType, nFieldLen, nFieldDec, nFieldNmbr, lOk, ;
      nFieldCount, cVarName, cVar

cFieldName := aStructure[nPointer,1]
cFieldType := aStructure[nPointer,2]
nFieldLen  := aStructure[nPointer,3]
nFieldDec  := aStructure[nPointer,4]

IF nAction = 1 // Validate field name

   nFound := AScan(aStructure,{|a|Upper(a[1])==Upper(cFieldName)})
   IF Empty(cFieldName)
      DC_WinAlert('Field name cannot be empty')
      RETURN .f.
   ELSEIF nFound # 0 .AND. nFound # nPointer
      DC_WinAlert('Duplicate Field Name.  Please re-enter')
      RETURN .f.
   ENDIF

ELSEIF nAction = 2 // Validate field type

   IF !(cFieldType $ 'CLMND')
      DC_MsgBox(,,{ ;
                 'Valid Field types are:', ;
                 '', ;
                 'C - Character', ;
                 'N - Numeric', ;
                 'D - Date', ;
                 'L - Logical', ;
                 'M - Memo'}, ;
                 'Field Type Error' )
      RETURN .f.
   ENDIF

ELSEIF nAction = 3 // Validate field Length

  IF nFieldLen <= 0
     DC_WinAlert('Length cannot be less than 1')
     RETURN .f.
  ENDIF

ELSEIF nAction = 4 // Validate field decimals

  IF cFieldType $ 'CDLM'
    aStructure[nPointer,4] := 0
  ELSEIF nFieldDec > nFieldLen - 2
     DC_WinAlert('Decimals cannot be greater than ' + ;
                  Str(nFieldLen-2))
     RETURN .f.
  ENDIF

ELSEIF nAction = 7 // When test for Field Length

  IF cFieldType $ 'MDL'
     RETURN .f.
  ENDIF
  RETURN .t.

ELSEIF nAction = 8 // When test for Field Decimals

  IF cFieldType $ 'MDLC'
     RETURN .f.
  ENDIF
  RETURN .t.

ENDIF

IF cFieldType = 'C'
   aStructure[nPointer,4] := 0
ELSEIF cFieldType = 'M'
   aStructure[nPointer,3] := 10
   aStructure[nPointer,4] := 0
ELSEIF cFieldType = 'D'
   aStructure[nPointer,3] := 8
   aStructure[nPointer,4] := 0
ELSEIF cFieldType = 'L'
   aStructure[nPointer,3] := 1
   aStructure[nPointer,4] := 0
ENDIF
oBrowse:refreshCurrent()

RETURN .t.

 /*
 This example demonstrates an array browse with source
 written to HTML.
 */

FUNCTION XTest2()

LOCAL i, j, GetList[0], cHtml, oBrowse, aDir := Directory()

@ 0,0 DCBROWSE oBrowse SIZE 4,10 DATA aDir

DCBROWSECOL ELEMENT 1 HEADER 'File Name' PARENT oBrowse
DCBROWSECOL ELEMENT 2 HEADER 'File Size' PARENT oBrowse
DCBROWSECOL ELEMENT 3 HEADER 'File Date' PARENT oBrowse
DCBROWSECOL ELEMENT 4 HEADER 'File Time' PARENT oBrowse

DCREAD HTML TO cHtml
MemoWrit('TEST.HTM',cHtml)

RETURN nil

Files:

DCDIALOG.CH

See Also:

   @ DCBROWSE
   @ DCQUICKBROWSE
   dc_htmlcolumn()


DCDOT

Invoke a Dot-prompt window

DCDOT will load DCLIP1.DLL and run the DC_Dot() function to invoke a Dot-Prompt window.

Syntax:

DCDOT

Arguments:

None.

Files:

DCDIALOG.CH

See Also:

   DC_Dot()
   DCQDEBUG


DCEVAL

Evaluate a code block in the GetList

DCEVAL is used to evaluate a code block when the GetList is processed by DCREAD HTML. The code block will be evaluated in the order that it appears in the Getlist.

Syntax:

DCEVAL <bEval>                                                     ;
       [PARENT <oParent>]                                          ;
       [PARENTID <cPID>]                                           ;
       [GROUP <cGroup>]                                            ;
       [WHEN <bWhen>]

Arguments:

<bEval> is the code block to evaluate.

PARENT <oParent> is the parent object.  The HTML source is
written only after all the objects are created from the GetList.
The code is written in a heirarchal sequence depending on the
parent/child relations.  PARENTID <cPID> may be used as an
alternative method to establish the parent where <cPID> is the
ID of the parent object.

GROUP <cGroup> is the group to which this GetList item belongs.

If the WHEN <bWhen> clause is used, then <bWhen> is evaluated
first.  If it returns a .TRUE. then <bEval> is evaluated otherwise
it is ignored.

Files:

DCHTML.CH

See Also:

   DCREAD HTML
   DC_ReadHtml()


DCFINDADDCOL

Add column to an array to be used by DCFINDBROWSE

DCFINDADDCOL is used to add a column to an array to be later used with DCFINDBROWSE or DC_FindBrowse().

Syntax:

DCFINDADDCOL                                            ;
     [DATA <nbData>] [ELEMENT <nElement>]               ;
     [FIELD <cField>]                                   ;
     [HEADER <cHeader> ]                                ;
     [WIDTH <nWidth> ]                                  ;
     [TAG,ORDER,INDEX <cIndexOrder>]                    ;
     [TAGPROMPT,ORDERPROMPT,INDEXPROMPT <cIndexPrompt>] ;
     [PREFIX <bcPrefix>]                                ;
     [SEEK <bSeek]                                      ;
     [TO <aArray>]

Arguments:

DATA <nbData> is a code block for the data to be displayed or
the element number if browsing an array. ex: {||CUSTOMER->name}
Alternatively, if browsing an array, the clause ELEMENT <nElement>
may be used.

 or

FIELD <cField> is the name of a database field.

HEADER <cHeader> is the heading of the column.

WIDTH <nWidth> is the width of the column

TAG | ORDER | INDEX <cIndexOrder> is the Index Name or Tag
(ex: "CUSTNAME") is the index tag to select when right clicking
the column header.  If browsing an array, this is the element
number to SORT.

TAGPROMPT | ORDERPROMPT | INDEXPROMPT <cIndexPrompt> is the
Index Prompt (ex: "Customer Name") that is displayed next to
the user input area when this column is selected as the
controlling index for the seek by right-clicking the column
header.

PREFIX <bcPrefix> is the Prefix for AutoSeek.  This must be a
character string or a code block.  If it is a code block, the
code block must return a character string.  The character string
is inserted before the user input buffer when performing the
seek.

SEEK <bSeek> is the Seek string code block. User input buffer
is passed to this code block and the return value of the code
block is used for the seek. If this argument is not used then
the contents of the user input buffer are used for the seek.

ex: {|c|Right(Space(7)+Alltrim(cString),7)}

TO <aArray> is the name of the array to add the column information.

Examples:

// Example 1 - Popup a Browse with multiple columns and AutoSeek

FUNCTION XTest()

LOCAL GetList := {}, oBrowse, aFields, aHeaders, aPres, nRecord

SET DEFA TO ..\XDOC
USE EXPRESS VIA FOXCDX EXCLUSIVE ALIAS 'XDOC'
SET INDEX TO EXPRESS.CDX
OrdSetFocus('COMMAND')
SET DEFA TO

aFields := {}

DCFINDADDCOL DATA {||XDOC->command} TAG 'COMMAND' PROMPT 'Command' ;
   HEADER 'Command' TO aFields

DCFINDADDCOL DATA {||XDOC->short} HEADER 'Short' TO aFields

DCFINDADDCOL DATA {||XDOC->type} HEADER 'Type' TO aFields  ;
   TAG 'TYPE' PROMPT 'Type'

DCFINDADDCOL DATA {||XDOC->module} HEADER 'Module' TO aFields  ;
   TAG 'TYPE' PROMPT 'Type' TO aFields

DCFINDADDCOL DATA {||XDOC->see_also} HEADER 'See Also' TO aFields

@ DCFINDBROWSE FIELDS aFields DATA 'XDOC' SIZE 50,10 AUTOSEEK

RETURN nil

// Example 2 - Browsing an array

FUNCTION FindDir()

LOCAL aFields := {}, lStatus, aDir := Directory()

DCFINDADDCOL DATA 1 PROMPT "File Name" ;
   HEADER 'File Name' WIDTH 10 TO aFields ORDER 1

DCFINDADDCOL DATA 2 PROMPT "File Size" ;
   HEADER 'File Size' WIDTH 10 TO aFields ORDER 2

@ 0,0 DCFINDBROWSE                         ;
       FIELDS aFields                      ;
       SIZE 50, 15                         ;
       TITLE 'Select a File'               ;
       AUTOSEEK                            ;
       DATA aDir                           ;
       NOHSCROLL ;
       TO lStatus

RETURN lStatus

Files:

DCDIALOG.CH

See Also:

   DC_FindBrowse()


DCFORM

A command for creating FORM tags in HTML

DCFORM is a command for creating HTML form elements.<br><br>The command DCFORM creates an HTML element definition and adds the definition to the array named GETLIST which is later processed by the DC_READHTML() function or by the DCREAD HTML command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD HTML creates all the DC_Html*() objects from the GetList array and then invokes the :writeHtml() method of the topmost parent object to generate the HTML code.<br><br>A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all objects referenced by the GetList array to be released.<br><br>

Syntax:

@ [ <nRow>,<nCol> ] DCFORM       ;
          [OBJECT <oForm>]       ;
          [PARENT <oParent>]     ;
          [PARENTID <cPID>]      ;
          [ACTION <cAction>]     ;
          [TARGET <cTarget>]     ;
          [ENCTYPE <cEncType>]   ;
          [METHOD <cMethod>]     ;
          [CARGO <xCargo>]       ;
          [HIDE <bHide>]         ;
          [EVAL <bEval>]         ;
          [PRE,PRETEXT <bcPreHtml>] ;
          [POST,POSTTEXT <bcPostHtml>] ;
          [TITLE <cTitle>]       ;
          [ID <cId>]             ;
          [GROUP <cGroup>]       ;

Arguments:

<nRow> and <nCol> are the row number and column number of
the table if the parent of this object is a DCTABLE. The
text will be inserted in the cell of the table defined by
the row/column.

ENCTYPE <cEncType> is the encoding type of the data submitted.
The default is "application/x-www-form-urlencoded". An
alternate type is "multipart/form-data".

ACTION <cAction> is the URL of the application that receives
and processes the form data.

METHOD <cMethod> is the method for sending the data to the
application server.  The valid options are "GET" and "POST".
For small forms with few variables use "GET".  For large
forms with many variables use "POST".

TARGET <cTarget> is the name of the window or frame which will
receive the posted data.

OBJECT <oForm> is the name of the variable to assign as a
storage place for this object.

PARENT <oParent> is the name of the variable that was
assigned to the parent of this object. If this argument
is not passed then the parent will be the object set with
the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container of object created by this definition.

PRE,PRETEXT <bcPreHTML> is a character string or a code block
that returns a character string containing any HTML text
that will precede the opening <table> tag in the source
that is written.

POST,POSTTEXT <bcPostHTML> is a character string or a code block
that returns a character string containing any HTML text
that will follow the closing </table> tag in the source
that is written.

HIDE <bHide> is a code block that is evaluated at the
time the :writeHtml() method is called for the class that
supports this command.  If the code block returns a .TRUE.,
then no HTML code will be written.

EVAL <bEval> is a code block that is evaluated after the
object is created in DC_ReadHtml().  A pointer to the
object associated with this command is passed as an
argument to the code block.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETOBJECT() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not used in the HTML output but is simply a description of the
get object which is saved in the GetList.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group.

Notes:

DCFORM creates an object of the DC_HtmlForm() class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], oForm, cHtml, oTable, cComment1, cComment2

DCFORM OBJECT oForm METHOD "POST" ;
  ACTION "http://donnay-software.com:8083"

DCTABLE OBJECT oTable PARENT oForm ROWS 2 COLUMNS 1 WIDTH '200'

cComment1 := 'This is memo 1'
cComment2 := 'This is memo 2'

@ 1,1 DCMULTILINE cComment1 PARENT oTable SIZE 30,10 NAME 'Memo1'
@ 2,1 DCMULTILINE cComment2 PARENT oTable SIZE 30,10 NAME 'Memo2'

DCREAD HTML TO cHtml

MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

DCHTML.PRG

See Also:

   DCREAD HTML
   dc_htmlform()
   dc_readhtml()


DCFRAME

A command for creating FRAME tags in HTML

The command DCFRAME creates an HTML FRAME definition and adds the definition to the array named GETLIST which is later processed by the DC_READHTML() function or by the DCREAD HTML command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD HTML creates all the DC_Html*() objects from the GetList array and then invokes the :writeHtml() method of the topmost parent object to generate the HTML code.<br><br> A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all objects referenced by the GetList array to be released.

Syntax:

DCFRAME                                                           ;
      [OBJECT <oObject>]           ;
      [PARENT <oParent>]           ;
      [PARENTID <cPID>]            ;
      [NAME <cName>]               ;
      [MARGINHEIGHT <nMarginHeight>]  ;
      [MARGINWIDTH <nMarginWidth>]    ;
      [NORESIZE]                   ;
      [NOSCROLL]                   ;
      [SRC,SOURCE <src>]           ;
      [FRAMEBORDER <nFrameBorder>] ;
      [BORDERCOLOR <cBorderColor>] ;
      [CARGO <xCargo>]             ;
      [HIDE <bHide>]               ;
      [EVAL <bEval>]               ;
      [PRE,PRETEXT <bcPreText>]    ;
      [POST,POSTTEXT <bcPostText>] ;
      [TITLE <cTitle>]             ;
      [ID <cId>]                   ;
      [GROUP <cGroup>]             ;

Arguments:

NAME <cName> labels the frame for later reference by the
"target" attribute of other HTML elements.

SRC <src> is the URL of the document that is to be
displayed in the frame.  There is no other way to provide
content for a frame.

MARGINHEIGHT <nMarginHeight> and MARGINWIDTH <nMarginWidth>
are used to put space (in pixels) between the edge of the
frame and its contents.

NORESIZE freezes the relative proportions of the frame
so it may not be resized.

NOSCROLL suppresses vertical and horizontal scrollbars
with frames whose contents exceed the allotted window
space.

FRAMEBORDER <nFrameBorder> is used to determine whether
or not there is a frame border.  A value of 1 turns on
the border.  A value of 0 turns off the border.

BORDERCOLOR <cBorderColor> is the color of the frame border.
Color may be an RGB color value (#XXXXXX) , a standard color
name, an RGB 3-element array or a numeric value defined in
GRA.CH.

OBJECT <oLink> is the name of the variable to assign as a
storage place for this object.

PARENT <oParent> is the name of the variable that was
assigned to the parent of this object. If this argument
is not passed then the parent will be the object set with
the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container of object created by this definition.

PRE,PRETEXT <bcPreHTML> is a character string or a code block
that returns a character string containing any HTML text
that will precede the opening <table> tag in the source
that is written.

POST,POSTTEXT <bcPostHTML> is a character string or a code block
that returns a character string containing any HTML text
that will follow the closing </table> tag in the source
that is written.

HIDE <bHide> is a code block that is evaluated at the
time the :writeHtml() method is called for the class that
supports this command.  If the code block returns a .TRUE.,
then no HTML code will be written.

EVAL <bEval> is a code block that is evaluated after the
object is created in DC_ReadHtml().  A pointer to the
object associated with this command is passed as an
argument to the code block.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETOBJECT() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not used in the HTML output but is simply a description of the
get object which is saved in the GetList.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group.

Notes:

DCFRAME creates an object of the DC_HtmlFrame() class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], cHtml, oFrameSet

DCFRAMESET OBJECT oFrameSet ;
      ROWS '60%,*'

DCFRAME ;
     PARENT  oFrameSet ;
     NAME 'donnay' ;
     SRC 'http://donnay-software.com'

DCFRAME ;
     PARENT oFrameSet ;
     FRAMEBORDER 0 ;
     NAME 'google' ;
     SRC 'http://www.google.com'

DCREAD HTML TO cHtml

MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

DCHTML.CH

See Also:

   DCREAD HTML
   dc_html()
   dc_readhtml()
   dc_htmlframe()


DCFRAMESET

A command for creating FRAMESET tags in HTML

The command DCFRAMESET creates an HTML FRAMESET definition and adds the definition to the array named GETLIST which is later processed by the DC_READHTML() function or by the DCREAD HTML command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD HTML creates all the DC_Html*() objects from the GetList array and then invokes the :writeHtml() method of the topmost parent object to generate the HTML code.<br><br> A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all objects referenced by the GetList array to be released.

Syntax:

DCFRAMESET                    ;
      [OBJECT <oObject>]      ;
      [ROWS <nRows>]          ;
      [COLS,COLUMNS <nCols>]  ;
      [NAME <cName>]          ;
      [FRAMEBORDER <nFrameBorder>] ;
      [BORDER <nBorder>]      ;
      [BORDERCOLOR <cBorderColor>] ;
      [PARENT <oParent>]      ;
      [PARENTID <cPID>]       ;
      [CARGO <xCargo>]        ;
      [HIDE <bHide>]          ;
      [EVAL <bEval>]          ;
      [PRE,PRETEXT]           ;
      [POST,POSTTEXT>]        ;
      [TITLE <cTitle>]        ;
      [ID <cId>]              ;
      [GROUP <cGroup>]        ;

Arguments:

COLS,COLUMNS <columns> and ROWS <rows> defines the number of
columns and rows of either frames or nested framesets.
Both attributes accept a quote-enclosed, comman-separated
list of values that specify either the absolute or relative
width (for columns) or height (for rows) for the frames.
The number of attribute valuess determines how many rows or
columns of frames will display in the document window.

Express each value in the <rows> or <columns> attribute
in one of three ways:

1. As absolute number of pixels.
2. As a percentage of the total width or height of the
frameset.
3. As a portion of the space remaining after setting aside
room for adacent elements.

Examples:<rows> = "150,300,150"
<rows> = "25%,50%,25%"
<columns> = "100,*"
<columns> = "10,*,10"
<rows> = "*,100,*"

NAME <cName> is the name to assign to the frameset.

FRAMEBORDER <nFrameBorder> is used to determine whether
or not there is a frame border.  A value of 1 turns on the
border.  A value of 0 turns off the border.

BORDER <nBorder> is the width of the frame border in pixels.

BORDERCOLOR <cBorderColor> is the color of the frame border.
Color may be an RGB color value (#XXXXXX) , a standard color
name, an RGB 3-element array or a numeric value defined in
GRA.CH.

OBJECT <oLink> is the name of the variable to assign as a
storage place for this object.

PARENT <oParent> is the name of the variable that was
assigned to the parent of this object. If this argument
is not passed then the parent will be the object set with
the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container of object created by this definition.

PRE,PRETEXT <bcPreHTML> is a character string or a code block
that returns a character string containing any HTML text
that will precede the opening <table> tag in the source
that is written.

POST,POSTTEXT <bcPostHTML> is a character string or a code block
that returns a character string containing any HTML text
that will follow the closing </table> tag in the source
that is written.

HIDE <bHide> is a code block that is evaluated at the
time the :writeHtml() method is called for the class that
supports this command.  If the code block returns a .TRUE.,
then no HTML code will be written.

EVAL <bEval> is a code block that is evaluated after the
object is created in DC_ReadHtml().  A pointer to the
object associated with this command is passed as an
argument to the code block.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETOBJECT() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not used in the HTML output but is simply a description of the
get object which is saved in the GetList.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group.

Notes:

DCFRAMESET creates an object of the DC_HtmlFrameSet() class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], cHtml, oFrameSet

DCFRAMESET OBJECT oFrameSet ;
      ROWS '60%,*'

DCFRAME ;
     PARENT  oFrameSet ;
     NAME 'donnay' ;
     SRC 'http://donnay-software.com'

DCFRAME ;
     PARENT oFrameSet ;
     FRAMEBORDER 0 ;
     NAME 'google' ;
     SRC 'http://www.google.com'

DCREAD HTML TO cHtml

MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

DCHTML.CH

See Also:

   DCREAD HTML
   dc_readhtml()
   dc_htmlframeset()
   dc_htmlframe()


DCGETOPTIONS

Set the options for the Dialog Reader

DCGETOPTIONS is used to add options to a single-dimensional array named GETOPTIONS. <br><br> Before using the DCGETOPTIONS command you must first declare the GetOptions array variable so: LOCAL GetOptions <br><br> The GETOPTIONS array is passed to the Dialog Reader via DC_ReadGui(), DC_ReadGets(), or DCREAD.<br><br> This documentation is broken into 2 sections to prevent problems with the Microsoft Help Compiler. See DCGETOPTIONS (2)

Syntax:

DCGETOPTIONS ;
    [NAME <cName>] ;
    [TITLE <cTitle>] ;
    [WINDOWHEIGHT <nWndHeight>] ;
    [WINDOWWIDTH <nWndWidth>] ;
    [ROWSPACE <nRowSpace>] ;
    [FONT <cFont>] ;
    [SAYFONT <cSayFont>] ;
    [SAYWIDTH <nSayWidth>] ;
    [SAYHEIGHT <nSayHeight>] ;
    [GETHEIGHT <nGetHeight>] ;
    [GETFONT <cGetFont>] ;
    [WINDOWROW <nWindowRow>] ;
    [WINDOWCOL <nWindowCol>] ;
    [ROWOFFSET <nRowOffset>] ;
    [COLOFFSET <nColOffset>] ;
    [MENU <acMenu> [MSGBOX <oMsgBox>]] ;
    [PIXEL] ;
    [BUTTONS <aButtons>] ;
    [ICON <nIcon>] ;
    [CHECKGET] ;
    [HELPFILE,HELPBLOCK <bcHelp>] ;
    [HELPCODE <cHelpCode>] ;
    [VISIBLE] ;
    [NOTRANSLATE] ;
    [SAYRIGHT] ;
    [BITMAP <nBitMap>] ;
    [PRESENTATION <aPres>] ;
    [SAYOPTIONS <nSayOpt>] ;
    [COLOR <anBGColor>] ;
    [NOMINBUTTON] ;
    [NOMAXBUTTON] ;
    [TABSTOP] ;
    [NOTABSTOP] ;
    [ABORTQUERY [MSG <bAbortQuery>]] ;
    [CLOSEQUERY [MSG <bCloseQuery>]] ;
    [EXITQUERY [MSG <bExitQuery>]] ;
    [QUITQUERY [MSG <bQuitQuery>]] ;
    [ROWPIXELS <nRowPixels>] ;
    [COLPIXELS <nColPixels>] ;
    [NOESCAPEKEY] ;
    [DESIGN [HOTKEY <nDesignHotKey>]];
    [SOURCECODE <cSource>] ;
    [TOOLTIPCOLOR <nTTFg>, <nTTBg>] ;
    [TOOLTIPFONT <cTTFont>] ;
    [BORDER <nBorder>] ;
    [EXITVALIDATE] ;
    [NOTASKLIST] ;
    [MINSIZE <nMinWidth>, <nMinHeight>] ;
    [MAXSIZE <nMaxWidth>, <nMaxHeight>] ;
    [NORESIZE] ;
    [NOTITLEBAR] ;
    [NOMOVEWITHOWNER] ;
    [ORIGIN <nOrigin>] ;
    [HILITEGETS <nbColor>] ;
    [COLORGETS <aColors>] ;
    [NOSUPERVISE] ;
    [HIDE] ;
    [NOBUSYPOINTER] ;
    [BUSY <cBusyMsg> ] ;
    [CASCADE] ;
    [AUTORESIZE] ;
    [RESIZE] ;
    [CONFIRM] ;
    [NOCONFIRM] ;
    [FITPAD <nFitPad>] ;
    [BUTTONALIGN <nButtonAlign>] ;
    [DISABLEDCOLOR <anDisabledColor>] ;
    [ENTERTAB] ;
    [PREEVAL <bPreEval> ] ;
    [EVAL <bEval>] ;
    [EDITPROTECT <bProtect>] ;
    [MESSAGEINTO <obMsgBox>] ;
    ... more >> See DCGETOPTIONS (2)

Returns:

Arguments:
The Dialog Options List is simply a single-dimensionsal array
of 60+ elements.  eXPress++ Dialog options are included in
DCDIALOG.CH.  Before using the DCGETOPTIONS command you should
declare the GetOptions array variable like so:

LOCAL GetOptions

The elements of the options array are defined as follows:

NAME <cName> is the name of the Dialog screen or application.
It must be all Upper Case characters no longer than characters
in length.  It is a unique name assigned to the dialog for saving
to the dCLIP++ DIALOG dictionary database.

TITLE <cTitle> is the title or description of the dialog.

WINDOWHEIGHT <nWndHeight> is the dialog window height in
pixels.

WINDOWWIDTH <nWndWidth> is the dialog window width in pixels.

ROWSPACE <nRowSpace> is the number of pixels between rows when
using text-based coordinates in the Getlist.  The default is 20.
This parameter does NOT affect font height.

SAYWIDTH <nSayWidth> is the default width for DCSAY objects if
the SAYSIZE parameter is not used with the DCSAY command.
SAYWIDTH 0 will cause all DCSAY objects (XbpStatic) to be
automatically sized to the size of the text taking into
consideration the selected font.

SAYHEIGHT <nSayHeight> is the default HEIGHT (in pixels) of the
SAY in DCGET and @..DCSAY..GET commands.  If this parameter is not
specified then the default height is 20.

FONT <cFont> is the default FONT for all child objects of the
dialog window.

SAYFONT <cSayFont> is the default FONT for DCSAY objects if the
FONT parameter is not used with the DCSAY command.  If this parameter
is not specified then the DCSAY object uses the font of the parent.

GETFONT <cGetFont> is the default FONT for DCGET and
@..DCSAY..GET objects if the FONT parameter is not used with the
DCGET or @..DCSAY..GET commands.  If this parameter is not
specified, then the object uses the font of the parent.

GETHEIGHT <nGetHeight> is the default HEIGHT (in pixels) of the
GET in DCGET and @..DCSAY..GET commands.  If this parameter is not
specified then the default height is 20.

BUTTONS <aButtons> is an optional multi-dimensional array of
buttons to add to the bottom of the dialog box.  Each button will
be added in sequence from left to right.  Each sub-array is an
array of 13 elements defining the buttons.

 Element      Type       Description
 -------      ----       ------------------------------------
    1          C         Button Caption
    2          N         Button Width (in pixels) Default is 60
    3          N         Button Height (in pixels) Default is 22
    4          B         Action Code Block
    5          X         Button Cargo
    6          N/C/O     Bitmap resource, name or object when element
                         7 is an object
    7          O         Configuration object of the DC_PushButtonXPConfig()
                         class.
    8          B         WHEN code block
    9          C/B       Tooltip text or codeblock
   10          C/O       Font compound name or font object
   11          N/A       Accelerator hotkey or array of hot keys.
   12          B         Menu Action Code Block

 NOTE: The BUTTONS array can be used to add custom buttons in
       addition to the buttons provided by DCREAD GUI BUTTONS
       @..DCPUSHBUTTON.

WINDOWROW <nWndRow> is the starting row of the dialog window
(in pixels).  If this argument is nt specified, then the dialog
will be centered vertically in the parent.

WINDOWCOL <nWndCol> is the starting column of the dialog window
(in pixels).  If this argument is not specified, then the dialog
will be centered horizontally in the parent.

ROWOFFSET <nRowOffset> is the row offset (in pixels) to add to
each dialog object.  The default is 0.

COLOFFSET <nColOffset> is the column offset (in pixels) to add
to each dialog object.  The default is 0.

MENU <acMenu> is a multi-dimensional array containing an optional
menu to attach to the top of the dialog window.  The menu must conform
to the specifications of menus returned by the menu dictionary system.
This may also be a character string of up to 8 characters containing
the NAME of the menu.  See DC_MenuLoad().   MSGBOX <oMsgBox> is the
message box object which will receive PROMPT messages from the menu
when the user navigates throug the menu.

The PIXEL argument forces all coordinates in the Getlist to be
based on pixels, otherwise they are text-based coordinates.

BITMAP <nBitmap> is the resource ID of a Bitmap that is linked into
the .EXE.  This bitmap will be sized to fill the main dialog window.

COLOR <anBGColor> is the color to use as the background for the
dialog window.  If <anBGColor> is a numeric value, then it must
be a GRA_CLR_* (defined in GRA.CH).  If <anBGColor> is an array,
it must contain three numeric values (R,G and B respectively).

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the Dialog window.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.

SAYOPTIONS <nSayOpt> is a set of text alignment options.
Objects created by the @..DCSAY command can be given a set of
options which are used to align the text within the rectangular
area of the say (XbpStatic) object. Constants defined in the
XBP.CH file are used for these options. These constants are
listed in the table below. If combinations of alignment options
are required, the sum of the appropriate constants must are
assigned to the instance variable :options .

 #define constants for aligning text

 Constant                  Description

 XBPSTATIC_TEXT_LEFT       Text is left aligned
 XBPSTATIC_TEXT_CENTER     Text is horizontally centered
 XBPSTATIC_TEXT_RIGHT      Text is right aligned
 XBPSTATIC_TEXT_TOP        Text is displayed at top
 XBPSTATIC_TEXT_VCENTER    Text is vertically centered
 XBPSTATIC_TEXT_BOTTOM     Text is displayed at bottom

 An alternate method of aligning text is by using the following
 defines in place of SAYOPTIONS <nSayOpt>:

  SAYRIGHT, SAYLEFT, SAYRIGHTBOTTOM, SAYLEFTBOTTOM, SAYRIGHTCENTER,
  SAYLEFTCENTER, SAYRIGHTTOP, SAYLEFTTOP, SAYCENTER, SAYBOTTOM
  SAYTOP

PREEVAL <bPreEval> is a code block that is evaluated before the
main dialog window (XbpDialog) is created.

EVAL <bEval> is a code block that is evaluated after the main
dialog window (XbpDialog) is created.  This code block is
evaluated before any items from the GetList are created and
added to the Dialog.  The Dialog object is passed to the code
block.

ICON <nIcon> is the resource ID of the ICON to place in the upper
left corner of the dialog window.

The CHECKGET argument causes all DCGET or @..DCSAY..GET objects
which GET a logical value to be displayed as a CheckBox rather
than a normal GET.

HELPFILE, HELPBLOCK <bcHelp> is the name of a *.HLP help file
or a code block to activate when the user clicks on the HELP
button on the bottom of the dialog window.  If <bcHelp> is a
file name then the HELPCODE associated with the object in focus
when the F1 key is pressed will be passed to the Windows Help
reader.  If <bcHelp> is a code block, the HELPCODE associated
with the object in focus with the F1 key is pressed will be
passed to the function referenced in the code block.

HELPCODE <cHelpCode> is the "default" help link to invoke in the
help file established by HELPFILE <bcHelp> when the F1 key is
pressed.  Any specific HELPCODE assigned to DC* commands will
override this help link if the F1 key is pressed when the
specific object has focus.

The VISIBLE argument will cause dialog objects in the GetList to
be displayed when they are created, otherwise the entire dialog
will not be displayed until all objects are created.

The default translation mode assumes that all coordinates in the
GetList are based on 0,0 being the upper left home position of the
display or parent object.  It is also assumed that coordinates are
text-based unless individually specified as pixel-based by the
PIXEL argument.   This will also insure that RELATIVE coordinates
are based on the coordinates of the relative objects specified in
the Getlist.  If the NOTRANLATE argument is specified, then
NO TRANLATIONS will occur when the objects are displayed by the
GUI reader and all coordinates are assumed to be based on 0,0
being the lower left home position of the display or parent object
and are all pixel-based.  After the GUI reader translates the
coordinates, it writes the translated coordinates back to the
Getlist and automatically sets this flag to .FALSE. so that
successive calls to the GUI reader with the translated Getlist
will not cause anomolies when displaying the objects.

The SAYRIGHT argument causes all GETLIST_SAY type objects in the
Getlist to be displayed with text right-justified, unless that
object specificies LEFT or CENTER justification via the
aGETLIST_OPTIONS element of the Getlist item.

NOMINBUTTON will suppress the painting of a minimize button on
the dialog window.

NOMAXBUTTON will suppress the painting of a maximize button on
the dialog window.

TABSTOP will cause all objects (Xbase Parts) to be set when using
the Tab key. The default for TabStop is .False. or OFF.  The
TabStop setting for individual objects can be force to ON or OFF
by using the TABSTOP or NOTABSTOP commands respectively in each
command to override the default setting.

NOTABSTOP will override the setting of TABSTOP in each command.
This clause is mutually-exclusive with the TABSTOP clause.

ROWPIXELS is the amount of pixels that equate to a row when using
text-based coordinates.  The default is 20.

COLPIXELS is the amount of pixels that equate to a column when
using text-based coordinates.  The default is 7.0.

When using text-based coordinates (default), the coordinates must
be converted to pixels because this is all that the Xbase parts
classes understand.  For example, the command @ 10,30 DCSAY 'Test'
will place the word 'Test' at row 200, column 210 (in pixels).
Using text-based coordinates can give an advantage over pixel-
based because the COLPIXELS and ROWPIXELS clauses can be used in
conjunction with the SAYFONT and GETFONT clauses to automatically
adjust the screen to fix the desktop at runtime.  See XDEMO.PRG
for a complete example.

ABORTQUERY will cause a Message Box to appear Confirming the
cancelling of operation when the Cancel button is clicked or the
ESCape key is pressed.  The optional clause MSG <bAbortQuery> is
a code block to evaluate.  If this code block is used, it must
return a logical value of .TRUE. to abort the dialog and must
contain it's own message window (if required)

CLOSEQUERY will cause a Message Box to appear Confirming the
cancelling of operation when the dialog window is close by
clicking on the X in the upper right corner or double clicking
the icon in the upper left corner.  The optional clause
MSG <bCloseQuery> is a code block to evaluate. If this code block
is used, it must return a logical value of .TRUE. to close the
dialog window and must contain it's own message window (if
required)

EXITQUERY will cause a Message Box to appear Confirming the
dialog exit when the OK or Exit button is clicked or an attempt
is made to exit with the ENTER key when using the ENTEREXIT
clause.  The optional clause MSG <bExitQuery> is a code block
to evaluate.  If this code block is used, it must return a
logical value of .TRUE. to exit the dialog and must contain it's
own message window (if required)

QUITQUERY will cause a Message Box to appear Confirming the
dialog exit when the user attempts to shut down the operating
system.  The optional clause MSG <bQuitQuery> is a code block
to evaluate.  If this code block is used, it must return a
numeric value of XBP_ALLOW (defined in XBP.CH) to exit the dialog
and must contain it's own message window (if required).  To
prevent the computer from shutting down if must return a numeric
value of XBP_REJECT.

NOESCAPEKEY will disable the ESCape key.  Normally, the ESCape
key will close the dialog window and cancel operation.

DESIGN HOTKEY <nDesignHotKey> is the hot key that will invoke the
"design" mode.  In this mode, objects may be moved or resized and
the new coordinates saved to the original source code.  Keys are
defined in APPEVENT.CH. Ex: DESIGN HOTKEY xbeK_ALT_D.

SOURCECODE <cSource> is the name of the source code (*.PRG) file
that contains the DC* commands which created the dialog GetList.
This is needed when using the pop-up Dialog Editor in DESIGN mode.
Changes made to a dialog are re-written to the source code file
only if the command is identified by an ID, GETID or SAYID clause.
NOTE: To insure that the source code is found by the application,
      include the full path.

TOOLTIPCOLOR <nTTFg>, <nTTBg> is the foreground color and
background color, respectively, of tooltips when using the
TOOLTIP clause on eXPress++ commands.  The default colors are
GRA_CLR_BLACK and GRA_CLR_WHITE.

TOOLTIPFONT <cTTFont> is the font compound name of the font
for tooltips when using the TOOLTIP clause on eXpress++
commands.

BORDER <nBorder> defines the border type of the dialog window.
Constants defined in the XBP.CH file can be assigned to <nBorder>.
The define constants start with XBPDLG_.

If a dialog is embedded as MDI client within another dialog,
Windows ignores all border styles except XBPDLG_RAISEDBORDERTHICK
and XBPDLG_RECESSDBORDERTHICK. In all other cases, a border is
displayed for MDI clients that corresponds to
XBPDLG_RAISEDBORDERTHICK.

EXITVALIDATE will traverse the GetList when the user clicks on
the OK button and test all validations.  If any validation fails,
the failed object will receive input focus and the dialog will
remain active.

NOTASKLIST will insure that the dialog window is not placed on
the Windows task bar.

MINSIZE <nMinWidth>, <nMinHeight>  is used to establish the
minimum size of the dialog window, in pixels,  if the operator
attempts to resize the window.  A value of -1 will set the height
or width to the height or width that was automatically set by the
FIT clause of DCREAD GUI.

MAXSIZE <nMaxWidth>, <nMaxHeight> is used to establish the
maximum size of tyhe dialog window, in pixels,  if the operator
attempts to resize the window. A value of -1 will set the height
or width to the height or width that was automatically set by the
FIT clause of DCREAD GUI.

NORESIZE will prevent the operator from resizing the dialog
window.

NOTITLEBAR will prevent a titlebar from displaying on the
dialog window.  This will also prevent the minimize, maximize,
and close buttons from appearing.

NOMOVEWITHOWNER will prevent the dialog window from automatically
moving when it's owner is moved.

ORIGIN <nOrigin> defines the reference point for the position of
the dialog window. The value of <nOrigin> must be a #define
constant from the file XBP.CH. The define constants start with
XBPDLG_ORIGIN_.

HILITEGETS <nbColor> will draw a box around the currently selected
GET.  The color of the box is defined by <nbColor> and must be
a GRA_CLR_* color defined in GRA.CH.  If <nbColor> is a codeblock
then it must return a numeric color. This clause highlights only
the GET portion of @.DCSAY..GET commands and DCGET commands.
NOTE: An anomoly in the XbpTabPage class causes this feature to
mess up the look of Tab Pages.  To prevent this problem it is
recommended that the Gets be first placed on a DCSTATIC object
which is in turn placed on the DCTABPAGE object.

COLORGETS <aColor> is used to establish an array of foreground
and background colors for determining the color of the GET portion
of @..DCSAY..GET and DCGET commands when the get is placed into
focus.  <aColor> is a two-dimensional array consisting of two
sub-array of 2 elements.  The first array contains the foreground
and background colors of the GET when it is selected.  The second
array contains the foreground and background color of the GET
when it is unselected.  If the second array is not used, then the
unselected color is GRA_CLR_BLACK on GRA_CLR_WHITE.  The color
definitions must conform to GRA_CLR_* definitions in GRA.CH.

 Example 1: COLORGETS { { GRA_CLR_WHITE, GRA_CLR_RED } }
 This will paint selected Gets White on Red, unselected Gets
 Black on White (default).

 Example 2: COLORGETS { { GRA_CLR_WHITE, GRA_CLR_RED }, '
                        { GRA_CLR_WHITE, GRA_CLR_BLUE } }
 This will paint selected Gets White on Red, unselected Gets
 White on Blue.

NOSUPERVISE will cause the ENTER key to move from the last get
of a group of gets to the first get of the next group of gets.
Normal behavior is for the movement from the last get to the
first get of a group of gets that all have the same parent.
For example, if there are gets on 3 different tab pages, and
the user is in the last get of TabPage 1, and ENTER will cause
the first get on TabPage  2 to acquire focus.

HIDE will hide the dialog window from view for later viewing
with the oDlg:show() method.

NOBUSYPOINTER will disable the busy hourglass mouse pointer
that displays by default when DC_ReadGui() is creating the
dialog objects.

BUSY <cBusyMsg> is a message to display in a progress window
when DC_ReadGui() is creating the dialog objects.

CASCADE will set the coordinates of the dialog window to an
offset from a sibling window that has the lowest coordinates.
This provides for cascading of dialog windows.  If there are
no siblings (windows belonging to the same parent), this
argument will be ignored.

AUTORESIZE is used to automatically resize and reposition all
child objects so they use the real estate of the parent dialog
in the same proportions as the child objects before the parent
was resized.  The complete childlist tree is resized.  If it
is desired to NOT resize ToolBars and Pushbuttons, then the
:resize callback of the dialog object must be overwritten
rather than using the AUTORESIZE clause as shown:

 bReSize :=  {|a,b,o,x|x := SetAppFocus(), ;
                            o:drawingArea:hide(), ;
                            DC_AutoReSize(a,b,o,GetList,.f.), ;
                            o:drawingArea:show(), ;
                            SetAppFocus(x) }

 DCREAD GUI .. EVAL {|o| o:resize := bReSize }

RESIZE is used to invoke the DC_ReSize() function to resize and
reposition child objects based on the rules defined by the RESIZE
clause of each DC* command.  If a DC* command does not invoke the
RESIZE clause, then that object will not be affected by the
resizing of the parent window.

CAUTION: Do not use DCGRA* commands with the RESIZE or AUTORESIZE
         clause of DCGETOPTIONS, unless the DCGRA* object is
         drawn on an object that does not get resized or
         repositioned at a later time. Auto-Sizing and Auto-
         Fitting is accomplished by traversing child list of
         the Parent object and reading the size and/or
         coordinates of all objects.  DCGRA*  commands are not
         objects, therefore they cannot be repositioned
         correctly.

CONFIRM causes all @..DCSAY..GETs and @..DCGETs to require that
the ENTER key be pressed to move to the next GET.

NOCONFIRM causes all @..DCSAY..GETs and @..DCGETs to move to the
next GET when the edit buffer is filled and a key is pressed in
the last position.

FITPAD <nFitPad> is the amount of pixels to use pad with dead
space around all objects when using the FIT clause of DCREAD GUI.
The default is 10.

BUTTONALIGN <nButtonAlign> is a numeric constant used to select
the method in which buttons should be aligned at the bottom of
the dialog window when using the ADDBUTTONS clause or the
BUTTONS <nButtons> clause of DCREAD GUI.  The constants are
defined in DCDIALOG.CH.  See the below table.

  Align Constant               Description
  ------------------------     -------------------------------
  DCGUI_BUTTONALIGN_LEFT  (*)  Align buttons to the left
  DCGUI_BUTTONALIGN_CENTER     Align buttons in the center
  DCGUI_BUTTONALIGN_RIGHT      Align buttons to the right

DISABLEDCOLOR <anDisabledColor> is a numeric constant or a
3-element array that is used to establish the background color
of objects that are disabled by the WHEN clause of DC* commands.
If <anDisabledColor> is a numeric value it must conform to the
GRA_CLR_* constants defined in GRA.CH.  If <anDisabledColor> is
an array, it must be 3 elements of numeric values in the range
of 0 - 255 to create an RGB color value.

ENTERTAB changes the behavior of the ENTER key when navigating a
table of GETs.  The default behavior is to navigate to the next
GET in the list of edit controls and if SET WRAP is ON, an ENTER
in the last GET wraps to the first GET.  The ENTERTAB clause
bypasses this logic and instead posts a TAB KEY event to the event
queue to process the ENTER key as though the TAB key was pressed.
Use this feature to overcome some problems related to LOSTFOCUS
clauses.

NOTRANSLATE will assume that coordinates are based on the
standard Xbase Parts coordinate system where the home position
is the lower left corner, otherwise all coordinates will be
translated for compatability with text-based applications and
other Windows applications with the home position as the upper
left corner.

EDITPROTECT <bProtect> is a code block to use as the "default"
code block to use for Edit controls such as DCGET, DCMULTILINE,
DCCOMBOBOX, DCCHECKBOX, and DCRADIOBUTTON.  This eliminates the
need to add an EDITPROTECT block to all edit controls in
applications that switch between a "view" and "edit" mode.

MESSAGEINTO <obMsgBox> defines the "default" message box object
to use for DC* commands that support the MESSAGE clause.  This
eliminates the need to add an INTO <oMsgBox> block to all
MESSAGE clauses.  <obMsgBox> may be a code block or a "prexisting
object".  For example, the message receptacle may be an XbpMle()
object for displaying multiple-line messages.  The string defined \
in the MESSAGE clause of the associated DC* command is passed to
the code block.

  Example:
    @ .. DCGET .. MESSAGE 'Message Line 1;Message Line 2'
    @ .. DCMULTILINE .. OBJECT oMsgBox
    DCGETOPTIONS ;
      MESSAGEINTO {|c|c:=Strtran(c,';',CRLF,oMsgBox:setData(c)}

If <obMsgBox> is an object, it must already exist and it must
support the :setCaption() method.

Notes:
 Many of the GET OPTIONS are not supported with the DCAPPEDIT, DCAPPFIELD, and DCAPPBROWSE commands as these commands are simple adaptations of the respective Xbase++ APPEDIT, APPFIELD, and APPBROWSE commands.

Examples:
  #include "dcdialog.ch"

  * ---- Example 1 ---- *

  PROCEDURE Xtest()

  LOCAL GetList := {}, GetOptions, cOption, oMyGroup

  cOption := 'P'

  @ 4,10 DCGROUP oMyGroup CAPTION "Select an Operation" ;
    SIZE 40,8

  @ 1,2 DCRADIO cOption PROMPT 'Save to Dictionary' VALUE 'D' ;
        PARENT oMyGroup

  @ 2,2 DCRADIO cOption PROMPT 'Save to Source Code' VALUE 'S' ;
        PARENT oMyGroup

  @ 3,2 DCRADIO cOption PROMPT 'Make a Backup file' VALUE 'B' ;
        PARENT oMyGroup

  @ 4,2 DCRADIO cOption PROMPT 'Pack the File' VALUE 'P' ;
        PARENT oMyGroup

  DCGETOPTIONS ;
    NOMAXBUTTON ;
    NOMINBUTTON ;
    WINDOWHEIGHT 400 ;
    WINDOWWIDTH 400 ;
    DESIGN ;
    VISIBLE ;
    ROWSPACE 30

  DCREAD GUI ;
    TITLE 'My Dialogue' ;
    OPTIONS GetOptions ;
    ADDBUTTONS

  RETURN

  * ---- Example 2 ---- *

  // Using the EXITQUERY clause to validate input

* -------------------

FUNCTION ExitQuery()

LOCAL GetList := {}, dStartDate := Date(), dEndDate := Date(), ;
      GetOptions, lOk

@ 1,1 DCSAY 'Start Date' GET dStartDate GETOBJECT oStartDate
@ 2,1 DCSAY '  End Date' GET dEndDate  GETOBJECT oEndDate

DCGETOPTIONS ;
   EXITQUERY MSG {||_Validate(dStartDate,dEndDate,oStartDate, ;
                              oEndDate)}

DCREAD GUI FIT ADDBUTTONS TO lOk OPTIONS GetOptions ENTEREXIT

RETURN lOk

* --------------

STATIC FUNCTION _Validate( dStartDate, dEndDate, oStartDate, ;
                           oEndDate )

IF dStartDate >= dEndDate
  DC_WinAlert('End Date must be greater than Start Date')
  SetAppFocus(oStartDate)
  RETURN .f.
ELSEIF Empty(dStartDate)
  DC_WinAlert('Start Date cannot be empty')
  RETURN .f.
  SetAppFocus(oStartDate)
ELSEIF Empty(dEndDate)
  DC_WinAlert('End Date cannot be empty')
  SetAppFocus(oEndDate)
  RETURN .f.
ENDIF

RETURN .t.

Files:
DCDIALOG.CH

See Also:
   DCGETOPTIONS (2)
   dc_getoptdefault()
   DIALOG GETLIST
   DCREAD GUI


DCGETOPTIONS (2)

Set the options for the Dialog Reader

DCGETOPTIONS (continued)

Syntax:

DCGETOPTIONS ;
    ... ;
    [AUTOWINDOWMENU] ;
    [NOWINDOWMENU] ;
    [KEYBOARD <cKeyString>] ;
    [NOEDITNAVKEYS <bNoEditNavKeys>] ;
    [AUTOFOCUS] ;
    [RESIZE] ;
    [RESIZEDEFAULT <aDefaultResize>];
    [SCALEFACTOR <aScaleFactor>] ;
    [DEFAULTFONT <cDefaultFont>] ;
    [ALWAYSONTOP] '
    [ONCLICK <bOnClick>] ;
    [RESTOREDEFAULTSBUTTON] ;
    [SCROLLBARS <nScrollBars>] ;
    [GETTEMPLATE <cTemplateChar>] ;
    [LOCKWINDOWTOOWNER]

Arguments:

AUTOWINMENU (eXPress++ version 1.7 or later) is used in MDI-based
applications where there is a main window with a pull-down menu and
many child windows that were created with DCREAD GUI .. APPWINDOW
<oMainWindow:drawingArea>.  This causes a "Window" menu item to be
automatically added to the main window menu bar when a child window
is opened with several window options.  Run the XDEMO.EXE program
for an example.

NOWINDOWMENU is used in MDI-based applications that also use the
AUTOWINDOWMENU clause.  It is used to prevent a dialog from being
added to the "window" menu when it is created.

KEYBOARD <cKeyString> is a string of keys to pass into the
keyboard queue.  The keys will be received by the first object
to get focus.  If <cKeyString> is a null string, then any keys
in the keyboard buffer placed by the Xbase++ KEYBOARD command
will pass into the keyboard queue.

NOEDITNAVKEYS <bNoEditNavKeys> is a code block that is evaluated
to disable the key navigation that moves between edit controls
when using the ENTER,  UP or DOWN keys.

Example: DCGETOPTIONS .. NOEDITNAVKEYS {||nTabPage==3}

AUTOFOCUS enables the restoration of focus to the object that
last had focus when the parent dialog window receives focus.
If an object is an "Edit Control" such as a DCGET or DCMULTILINE
then it will automatically receive focus if it last had focus.
This is required so as not to defeat validation rules.  Objects
which are not "Edit Controls" such as a DCPUSHBUTTON will be
restored focus only if the AUTOFOCUS clause is used.

RESIZE is used in conjunction with the RESIZE clauses of DC*
commands. This clause creates a resize callback to use DC_Resize()
as the function for resizing and repositioning child objects
after the parent window has been resized.  Most DC* commands
include a RESIZE clause to establish the rules for how the
object associated with that command will be resized and/or
repositioned.

Each RESIZE clause of an @ .. DC* command accepts an an array
of two elements:

The first element is an optional code block that must return
two numeric values which will be the new X and Y position of
the object after its parent has been resized.  The code block
is passed two numeric arguments equivalent to the X delta and
the Y delta of the parent after it has been resized.  The second
element is an optional code block that must return two numeric
values which will be the new X and Y size of the object after
its parent has been resized.  The code block is passed two
numeric arguments equivalent to the X delta and the Y delta of
the parent after it has been resized.

Examples:

@ .. DCSAY 'Testing' ;
  RESIZE { {|x,y,o|{ o:currentPos()[1], o:currentPos()[2] + y} },;
           {|x,y,o|{ o:currentSize()[1] + x, o:currentSize()[2] + y} } }

Note: DCDIALOG.CH contains DCGUI_RESIZE_* constants for commonly used
      resizing rules.

RESIZEDEFAULT <aDefaultResize> is an array to use for the default
resizing rules.  See RESIZE above.

SCALEFACTOR <aScaleFactor> is an array of 5 elements to be used
for adjusting the X,Y size and position of objects.  Each value
is multiplied by the scale factor.

 Element  Type  Description           Default
 -------  ----  -------------------   -------
   [1]     N    Column position          1
   [2]     N    Row position             1
   [3]     N    Width                    1
   [4]     N    Height                   1
   [5]     L    Automatic Font Scaling  .F.
   [6]     L    Automatic Re-Scaling*   .F.

* This means that a window that has been resized to 50% larger
will be automatically re-scaled 50% larger the next time it is
created.

DEFAULTFONT <cDefaultFont> is the default font to use for all DC* commands.

ALWAYSONTOP will cause the dialog window to always stay on top
of other desktop windows.

ONCLICK <bOnClick> is a code block to evaluate whenever the left
mouse button is clicked on any object of a dialog window.  The
following parameters are passed to the evaluated code block:
oXbp : the object clicked on.
GetList : a pointer to the GetList array.

ENTEREXIT will exit the dialog if the ENTER key is pressed.  The
exact behavior is determined by the DC_EnterExitMode() function.
The default behavior is to exit the dialog when the ENTER keys is
pressed in the "last GET".  If this option is not used, then pressing
the ENTER key in the last GET will cause the first GET to receive
focus provided that SET WRAP is ON, otherwise pressing ENTER in the
last GET will have no affect.

RESTOREDEFAULTSBUTTON a right-click area in the lower left corner of
each dialog.  Clicking in this area will popup a message box
allowing the user to restore the screen position and size to the
defaults.  This is used in conjunction with DC_AutoRestoreWindow().

SCROLLBARS <nScrollBars> will cause scrollbars to automatically
appear in the drawingArea of the dialog window if a child object
is displayed outside the drawing area.

Example: SCROLLBARS XBP_SCROLLBAR_VERT+XBP_SCROLLBAR_HORIZ

GETTEMPLATE <cTemplateChar> is the character to use to determine
the width of a DCGET object. Gets are automatically sized to the
number of characters in the associated variable.  This does not work
as well for proportional fonts and for fixed fonts, therefore
this sets the template character that is used to determine the size
of a DCGET when using a proportional font.  The default is 'W'.

TOOLTIPFONT <cTTFont> is the font to use for tooltips.

LOCKWINDOWTOOWNER insures that a window (even modal windows) cannot be
moved outside the perimeter of the owner window.

Files:

DCDIALOG.CH

See Also:

   DCGETOPTIONS


DCGRUMPBROW

An emulation of Greg Lief's GRUMPBROW

DCGRUMPBROW is an emulation of the GrumpFish command GRUMPBROW originally written for Clipper 5.x. It is full GUI and is based on the eXPress++ DC* command set rather than Tbrowse().<br><br>

Syntax:

DCGRUMPBROW                             ;
         [ TO <var> ]                               ;
         [ SECURITY <cSec> ]                        ;
         [ TOP <nTop> ]                             ;
         [ LEFT <nLeft> ]                           ;
         [ BOTTOM <nBottom> ]                       ;
         [ RIGHT <nRight> ]                         ;
         [ TITLE <cTitle> ]                         ;
         [ FIELDS <aFields> ]                       ;
         [ HEADINGS <aHeadings> ]                   ;
         [ PICTURES <aPictures> ]                   ;
         [ ALTERNATES <aAlternates> ]               ;
         [ LOW <xLow> ]                             ;
         [ HIGH <xHigh> ]                           ;
         [ EXTRA  <aExtraOptions> ]                 ;
         [ EXTRAKEY <nExtraOptionsKey> ]            ;
         [ EXTRATITLE <cExtraOptionsTitle> ]        ;
         [ EXITKEY <nExitKey> ]                     ;
         [ INDEX_DESCRIPTION <aIndexDescriptions> ] ;
         [ VALIDS <aValids> ]                       ;
         [ WHENS <aWhens> ]                         ;
         [ AUTOREFRESH <nSeconds> ]                 ;
         [ LOCK <nlock> ]                           ;
         [ CARRY ]                                  ;
         [ MEMOWIDTH <nMemoWidth> ]                 ;
         [ MEMOHEIGHT <nMemoHeight> ]               ;
         [ COLORBLOCKS <aBlocks>   ]                ;
         [ INITIAL <bIinitial>  ]                   ;
         [ GOTOP ]                                  ;
         [ ALTERNATE_KEYS <aKeys> ]                 ;
         [ PRESENTATION <aPres> ]                   ;
         [ WIDTHS <aWidths> ]                       ;
         [ EDITCOORDS <aEditCoords> ]               ;
         [ MENU <acMenu> ]                          ;
         [ FONT <cFont> ]                           ;
         [ GETLIST @<aGrumpGetList> ]               ;
         [ MODAL ]                                  ;
         [ PARENT @<oDlg> ]                         ;
         [ APPWINDOW <oAppWindow> ]

Arguments:

SECURITY <cSec> is a string defining the security level you want to
give your users.  Case is not significant. You pass the first
letter of each feature that you wish to activate:

  A    Add
  E    Edit
  D    Delete
  P    Screen Painter // not supported
  Q    Query by example
  S    Search*
  V    View
  N    do Not allow individual field edit (see below)
  C    allow cell (individual field edit) only (no full-screen)
  K    allow user to pack the database
  I    allow user to swap index with ALT-I
  L    allow user to lock column with "L"
  F    allow user to "filter" (show data subset) with ALT-S
  O    output (print) all or some records (can be overridden
         as item #8 in <aAlternates>... see below)

 If you do not pass this parameter, all the user will be able to do is
 browse vertically and Esc when they are finished.

 *If no index file is open, or if the index key is not of character
 type, you will not be able to Search, regardless of whether or not
 you pass an "S" in <cSecurity>.

TOP <nTop>, LEFT <nLeft>, BOTTOM <nBottom>, RIGHT <nRight>
delineate the screen region to be used for the browse.  The default
values are 0, 0, 24, and 79, respectively.

FIELDS <aFields> contains character strings holding the names of the
fieldnames to show in the browse. Skip this parameter entirely if
you want to show all fields in the currently active database.

 SPECIAL NOTE: you can alternatively put code blocks in <aFields>
 to show any valid Xbase++ expression.  Note that any such columns
 will not be editable unless they are Get/Set code blocks.  These
 code blocks can be used for just about anything, including fields
 in databases other than the currently active work area.  You may
 also wish to make these code blocks "get-set", which means that
 they can assign values.  For example, the following code block
 displays the CUST->LASTNAME field and allows the user to edit it
 as well:

    { | x | if(x == NIL, cust->lastname, cust->lastname := x) }

HEADINGS <aHeadings> contains an array of column headings to be used
for the browse.  If you do not use this clause, the fieldnames will
be used as column headings.NOTE: No default heading will be provided
for columns that are based on code blocks (see <aFields> description
above).

PICTURES <aPictures> contains PICTURE clauses corresponding to each
field.  You may use this if, for example, you wish to truncate certain
fields or use "Y" for logicals.  If you do not pass this parameter,
DC_GuiGrumpBrow() will establish default PICTURE values for each
field that conform to the general norm.  Use a null string if you
do not wish to use this parameter.

ALTERNATES <aAlternates> is an eight element array which is used to
override the default add/edit/etc. routines.  This array should be
eight elements long, and each element should contain either a code
block or a NIL.  The elements correspond to the actions as follows:

 aAlternate[1] = ADD function
 aAlternate[2] = DELETE function
 aAlternate[3] = EDIT function
 aAlternate[4] = QUERY function
 aAlternate[5] = SEARCH function
 aAlternate[6] = VIEW function
 aAlternate[7] = CELL EDIT codeblocks (see below)
 aAlternate[8] = OUTPUT function

 You only need to fill the elements that you wish to use. For
 example, if you want to use your own Add and Edit routines, you
 could do the following:

 LOCAL aAlternate[8]
 aAlternate[1] = { || SpecAdd() }
 aAlternate[3] = { |b| SpecEdit(b)}

 When the user presses "A" to Add or "E" to Edit, DC_GuiGrumpBrow()
 would evaluate these blocks and call SpecAdd() or SpecEdit(),
 respectively.  Note that the second code block accepts a parameter
 and passes it directly to SpecEdit().  This takes advantage of the
 fact that DC_GuiGrumpBrow() will automatically pass the Browse
 object and GetList to your alternate functions.  You can therefore
 manipulate the object as desired (e.g., resizing the window,
 forcing a manual refresh, etc).

 The seventh element of ALTERNATES array can contain an array
 containing code blocks for the columns where alternate cell editing
 is necessary.

LOW <xLow> and HIGH <xHigh> allow you to restrict browsing operations
to a subset of records, ie a SCOPE.  These parameters may be of any
data type -- conversion will be handled internally by DCGRUMPBROW.
Note that the subset feature works only if you have an index file
open.  Further note that if you have two indexes open, and wish to
switch between them using ALT-I,  DCGRUMPBROW will maintain a
different data subset for each index.

EXTRA <aExtraOptions> contains additional options which can be
accessed as a pop-up menu from within DCGRUMPBROW.  The default key
to pop up this menu is ALT-F10, although this can be changed.

Create an array that contains nested arrays, each of which contains
the menu option as the first element and the code block to be
executed as the second element.  For example:

 { ;
    { "First option",  { || firstfunc() }     }, ;
    { "Second option", { || secondfunc() }    }, ;
    { "Third option",  { | a,b | thirdfunc(a,b) } }  ;
 }

Note that the third code block accepts a parameter and sends it
through to the function.  This is because DCGRUMPBROW will
pass the Browse object and GetList as parameters to your code
blocks when it evaluates them.  Therefore you can write your code
blocks in this fashion to access the Browse object and manipulate
it as you see fit.

EXTRAKEY <nExtraOptionsKey> can be used to override the default
(ALT-F10) key to pop up the additional options menu.

EXTRATITLE <cExtraOptionsTitle> will be used as the title for the
pop-up menu window.  By default, no title will be used.

EXITKEY <nExitKey> allows you to use a different key for exiting the
browse. Pass the INKEY value of the desired key as this parameter.
The default is K_ESC.  If you wish to allow multiple exit keys, you
may pass an array containing the desired INKEY values as this
parameter (or in conjunction with the EXITKEY clause of the
DCGRUMPBROW user-defined command).

INDEX_DESCRIPTION <aIndexDescriptions> contains descriptive character
strings for each active index.  If you pass this parameter, these
descriptions will be displayed on the top row when users switch
between indexes with ALT-I.  Otherwise, the regular indexkey will be
displayed.

VALID <aValids> and WHEN <aWhens> allow you to attach VALID and
WHEN clauses to any or all columns in the browse.  If you use these,
you must use code blocks, and I would recommend generic coding to take
advantage of the GET object being passed as a parameter (e.g.,
{ |o| !empty(o:editBuffer()) }).  Note that these will apply to
both single-field and full-screen editing, as well as adding new
records.

AUTOREFRESH <nAutoRefresh> is ideal for multi-user programs.  If you
pass a numeric expression as this parameter, DCGRUMPBROW will
automatically refresh the screen as often as you specify. Your
parameter represents the number of seconds.

LOCK <nLockedColumns> is a numeric indicating how many columns should
be locked from the outset.  By default this will be zero.

CARRY enables the values from the current record to be carried
forward as the defaults for new records.  Pass a logical True if you
want this behavior.

MEMOWIDTH <nMemoWidth> is a numeric indicating the width to use for
memo windows.  By default, this will be either 40 or the width of the
browse window, whichever is smaller.

TITLE <cTitle> is a character string to be centered on the top row of
the DC_GuiGrumpbrow() window.  By default, no title will be used.
<nMemoHeight> is a numeric indicating the height to use for memo
windows.  By default, this will be eight rows.

COLORBLOCK <aColorBlocks> allows you to initialize the colorBlock
instance variable for one or more columns within the browse. This
array should contain either code blocks or NILs.

INITIAL <bInitial> will be evaluated just prior to the browse being
displayed.  This allows you to manipulate the browse object (e.g.,
changing the separators, changing the defColor instance variable for
one or more columns, moving the cursor to some column other than the
first, etcetera). Your codeblock should be structured to accept one
parameter, which will be the browse object.

GOTOP enables you to force DCGRUMPBROW to move to the top
of the database each time that the user presses ALT-I to cycle
through the active indexes.  Pass .T. if you desire this behavior.
By default, the record pointer will remain unchanged, unless a data
subset has been established for the index you are switching to, in
which case the record pointer will be moved to the first record in
said subset.

ALTERNATE_KEYS <aAlternateKeys> can be used to override the default
keys listed below for each DCGRUMPBROW behavior. This array would
contain nested arrays which correspond to the following actions:

    Element   Action     Default Key    Default Message
    aKeys[1]  ADD             A         [A]dd
    aKeys[2]  DELETE          D         [D]elete
    aKeys[3]  EDIT            E         [E]dit
    aKeys[4]  QUERY           Q         [Q]uery
    aKeys[5]  SEARCH          S         [S]earch
    aKeys[6]  VIEW            V         [V]iew
    aKeys[7]  (n/a)
    aKeys[8]  OUTPUT          O         [O]utput
    aKeys[9]  LOCKCOLUMN      L         [L]ock
    aKeys[10] SUBSET          Alt-S     [Alt-S]ubset
    aKeys[11] SWAPINDEX       Alt-I     [Alt-I]ndex
    aKeys[12] PACK            K         pac[K]

The structure of each nested array is { <nInkeyValue>,
<cPrompt> }. If you do not need to change a particular key,
simply leave that array element NIL.

If you do not want to have any key tooltips displayed, simply pass
NIL as the second element of each nested array.

PRESENTATION <aPresParam> is an array of presentation parameters for
the browse object.  See the Xbase++ documentation for the XbpBrowse()
class for a specification of this array.

WIDTHS <aColWidths> is an array of numeric values for each browse
column, one for each element of <aFields>.  For automatic sizing
insert a NIL in the array.

EDITCOORDS <aEditCoords> is an array of coordinates that defines the
location of the SAY (Header) prompt and GET (data) of each item in
<aFields> when using the full-screen editor.  Each element of
<aEditCoords> is a sub-array of 7 elements:

 <aEditCoords> element  Type     Description
 ---------------------  -------  --------------------------------
          1             Numeric  SAY (Header) Start Row
          2             Numeric  SAY (Header) Start Column
          3             Numeric  SAY Size (columns) default is 25
          4             Numeric  SAY Options - XBPSTATIC_TEXT_*
          5             Numeric  GET (Data) Start Row
          6             Numeric  GET (Data) Start Column
          7             Numeric  GET Size (columns) default is
                                 field width

MENU <acMenu> is a Menu array or menu name that conforms to the
specifications for DC_MenuEdit().

FONT <cBrowFont> is the font style for the browse.  This is a
character string that must conform to a standard Xbase++ font
declaration, ex: "8.Arial".  The default is "8.Courier".

GETLIST @<aGrumpGetList> is a variable (passed by reference) to
store a pointer to the GetList that will be created by
DC_GuiGrumpBrow().

MODAL will cause the dialog window to be Application Modal,
otherwise it will be modeless.

PARENT @<oDialog> is a reference to a parent dialog or to a
memory variable to store a reference to the dialog that will be
created.  If <oDialog> has already been created as an Xbase Parts
class object, it will become the parent for all the objects in
the GetList.  If <oDialog> is passed by reference as a NIL, the
dialog object created by the reader will be stored in this
memory variable.  NOTE: Xbase++ does not allow <oDialog> to be
a PRIVATE or a PUBLIC variable if it is passed by reference.

The parent of the dialog that will be created is referenced by
APPWINDOW <oAppWindow>.  If no <oAppWindow> argument is used
then the parent of the created dialog will be AppDeskTop().

Notes:

MEMO SUPPORT

Memofields are shown in the browse window as "<memo>". To view amemo, highlight it and press Enter.

When adding, editing, or doing a query by example, you will noticethat memo support is handled quite neatly. As you go through the GETlist, when you hit a memo, a small window will open for you to editthe memo.

SECURITY LEVELS

You may define different security levels at different parts of the program. For example, you might want to give your users the abilityto add and edit records at one part of the program, but only view records elsewhere.

SEARCH

If you press "S" to search, and if the current controlling index isof character type, you may jump quickly to records by typing in thefirst few letters of the desired value. For example, searching forthe name 'MCALLISTER' could prove quite tedious in a 750-recorddatabase, but with quick-search you need only type in the letters"M", "C", and "A" to narrow the scope down considerably. As lettersare added to the search string, it is redisplayed centered along thebottom row of the browse box (unless the new letter results in avalue that is not FOUND() in the database). You may press backspaceto erase the rightmost character of the search string.

SWAPPING INDEXES (Alt-I)

If you have two index files open, you may switch between them bypressing Alt-I. This means that you could have one index on companyname and another on last name, and jump back and forth between themfor searches.

QUERY BY EXAMPLE

By pressing "Q" you can do a query-by-example to find the nextrecord matching their specific criteria. All you need do is fill inthe blanks. Fill in as many fields as you want to narrow the searchcriteria. Note that all query-by-example searches arecase-insensitive.

If you want to search for a field that contains a certain value, theymay enter that value surrounded by two periods ("..") on either side.For example, if you wanted to find the next record that contains theword "STREET" in the address field, you could enter "..STREET.." forthat field.

After you perform a query-by-example, the next time you press "Q" youwill be given the option to repeat the search using the same criteria(which will save you the bother of re-entering it).

SCREEN PAINTER

The screen painter will be supported in a future version

EDITING ONE FIELD

When the user highlights a field and press Enter, they can edit itdirectly without going to a vertical view. (This assumes, ofcourse, that you have given them Edit privileges.) If they wish toedit the same field in a series of records, they can terminate theREAD by pressing the down arrow, which will move them down onerecord and pop them immediately into edit mode.

However, there may be situations when you do not want the user to beable to edit an individual field. In such situations, you shouldinclude "N" as part of the security parameter.

By the same token, there may be situations where you only wantthe user to be able to edit individual fields (as opposed to afull-screen edit). This would apply if you had a number of codeblock (and thus non-editable) columns. In such situations, youshould include "C" (and not "N") as part of the security parameter.

Files:

DCGRUMP.CH

See Also:

   dc_guigrumpbrow()


DCHOTKEY

Set a Hot-Key for action by the GUI Reader

The command DCHOTKEY creates a new Hot-Key object and adds the object to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD GUI command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released.<br><br> DCHOTKEY objects are used to set establish hot-keys which will execute pre-defined code-blocks from within the event loop of the GUI reader. <br><br> <br><br>

Syntax:

 DCHOTKEY <anAccel> ;                                                ;
          [ACTION <bAction>] ;
          [PARENT <oParent>] ;
          [PARENTID <cParentId>] ;                                       ;
          [WHEN <bWhen>] ;
          [ID <cId>] ;
          [TITLE <cTitle>] ;
          [GROUP <cGroup>]

Arguments:

<anAccel> is a numeric "hot-key" assignment that will activate
the <bAction> codeblock the hot-key is pressed.  The key must be
a valid key with the prefix xbeK_*.  These keys are defined in
APPEVENT.CH.  <anAccel> may also be an array of numeric values
to assign more than one key to an action.

ACTION <bAction> is the code block to evaluate when the key
is pressed in the DC_ReadGUI() event loop.  The code block
should look like so:

 { | uNIL1, uNIL2, oXbp | ... }

PARENT <oParent> is an optional parent object that is tied to
this key.  If this option is used, then the <bAction> code block
will be evaluated only if the <nAccel> key is pressed when the
parent object is in focus.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the hot-key will be disabled.  If the
value returned is .TRUE. then the hot-key will be enabled.
The object is passed as a parameter to the code block.

ID <cID> is a unique ID code to assign to this object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

Examples:

  #include "dcdialog.ch"
  #include "appevent.ch"

  PROCEDURE Xtest()

  LOCAL GetList := {}, GetOptions, cOption, oRadio1, oRadio2, ;
        oRadio3, oRadio4

  cOption := 'P'

  @ 1,2 DCRADIO cOption PROMPT 'Save to &Dictionary' VALUE 'D' ;
    OBJECT oRadio1

  @ 2,2 DCRADIO cOption PROMPT '&Save to Source Code' VALUE 'S' ;
    OBJECT oRadio2

  @ 3,2 DCRADIO cOption PROMPT 'Make a &Backup file' VALUE 'B' ;
    OBJECT oRadio3

  @ 4,2 DCRADIO cOption PROMPT '&Pack the File' VALUE 'P' ;
    OBJECT oRadio4

  DCHOTKEY xbeK_ALT_D ACTION {||SetAppFocus(oRadio1), ;
                                   oRadio2:SetData(.f.), ;
                                   oRadio3:SetData(.f.), ;
                                   oRadio4:SetData(.f.), ;
                                   oRadio1:SetData(.t.), ;
                                   cOption := 'D' }

  DCHOTKEY xbeK_ALT_S ACTION {||SetAppFocus(oRadio2), ;
                                   oRadio1:SetData(.f.), ;
                                   oRadio3:SetData(.f.), ;
                                   oRadio4:SetData(.f.), ;
                                   oRadio2:SetData(.t.), ;
                                   cOption := 'S' }

  DCHOTKEY xbeK_ALT_B ACTION {||SetAppFocus(oRadio3), ;
                                   oRadio1:SetData(.f.), ;
                                   oRadio2:SetData(.f.), ;
                                   oRadio4:SetData(.f.), ;
                                   oRadio3:SetData(.t.), ;
                                   cOption := 'B' }

  DCHOTKEY xbeK_ALT_P ACTION {||SetAppFocus(oRadio4), ;
                                   oRadio1:SetData(.f.), ;
                                   oRadio2:SetData(.f.), ;
                                   oRadio3:SetData(.f.), ;
                                   oRadio4:SetData(.t.), ;
                                   cOption := 'P' }

  DCREAD GUI ;
    TITLE 'Hot-Key Demo';
    FIT ;
    ADDBUTTONS

  DC_MsgBox({cOption})

  RETURN

Files:

DCDIALOG.CH


DCHTML

A command for creating any HTML output

The command DCHTML creates an HTML element definition and adds the definition to the array named GETLIST which is later processed by the DC_READHTML() function or by the DCREAD HTML command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD HTML creates all the DC_Html*() objects from the GetList array and then invokes the :writeHtml() method of the topmost parent object to generate the HTML code.<br><br> A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all objects referenced by the GetList array to be released.

Syntax:

@ [ <nRow> ,<nCol> ] DCHTML           ;
         [TEXT <bcText>]              ;
         [PRE,PRETEXT <bcPreHTML>]    ;
         [POST,POSTTEXT <bcPostHTML>] ;
         [OBJECT <oObject>]           ;
         [PARENT <oParent>]           ;
         [PARENTID <cPID>]            ;
         [STYLE,FONT <cStyle>]        ;
         [CARGO <xCargo>]             ;
         [TOOLTIP <bcToolTip>]        ;
         [HIDE <bHide>]               ;
         [EVAL <bEval>]               ;
         [TITLE <cTitle>]             ;
         [ID <cId>]                   ;
         [GROUP <cGroup>]             ;
         [MESSAGE <cMessage>]

Arguments:

<nRow> and <nCol> are the row number and column number of
the table if the parent of this object is a DCTABLE. The
text will be inserted in the cell of the table defined by
the row/column.

TEXT <bcText> is a character string or a codeblock that
returns a character string containing the HTML text or
plain text.

OBJECT <oTable> is the name of the variable to assign as a
storage place for this object.

PARENT <oParent> is the name of the variable that was
assigned to the parent of this table. If this argument
is not passed then the parent will be the object set with
the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

TOOLTIP <bcToolTip> is a tooltip to display over the text.

PRE,PRETEXT <bcPreHTML> is a character string or a code block
that returns a character string containing any HTML text
that will precede the opening <table> tag in the source
that is written.

POST,POSTTEXT <bcPostHTML> is a character string or a code block
that returns a character string containing any HTML text
that will follow the closing </table> tag in the source
that is written.

HIDE <bHide> is a code block that is evaluated at the
time the :writeHtml() method is called for the class that
supports this command.  If the code block returns a .TRUE.,
then no HTML code will be written.

STYLE <cStyle> is the style tag to wrap around the text.  For
example STYLE "H3" will create the following source:
<H3><bcText></H3>.

MESSAGE <bcMessage> is a character string or a codeblock
that returns a character string containing a message to
assign to the MESSAGEINTO <cMessageInto> clause of DCREAD
HTML when the mouse is clicked on the element in the browser.
This creates an <a href> around the element and sends a URL
equivalent to /?<cMessageInto>=<bcMessage>.

EVAL <bEval> is a code block that is evaluated after the
object is created in DC_ReadHtml().  A pointer to the
object associated with this command is passed as an
argument to the code block.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETOBJECT() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not used in the HTML output but is simply a description of the
get object which is saved in the GetList.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container of object created by this definition.

Notes:

DCHTML creates an object of the DC_Html() class.

Examples:

/*
This example will create a table containing four sub tables
and write into each sub table.
*/

FUNCTION HtmlCommand()

LOCAL i, j, GetList[0], cHtml, oTable, nTable, aSubTables[2,2]

DCTABLE OBJECT oTable1 ;
     ROWS 2 ;
     COLUMNS 2 ;
     BORDER 5 ;
     BORDERCOLOR '#336677' ;
     TRIMROWS ;
     TRIMCOLS ;
     BGCOLOR '#339977'

nTable := 1
FOR i := 1 TO 2
  FOR j := 1 TO 2
    @ i,j DCTABLE ;
      OBJECT aSubTables[i,j] ;
      BGCOLOR '#33AA77' ;
      ROWS 1 ;
      COLUMNS 1 ;
      PARENT oTable1
      @ 1,1 DCHTML TEXT '<h2>This is table</h2><h1>' + ;
            (Str(nTable++))+'</h1>' ;
            PARENT aSubTables[i,j]
  NEXT
NEXT

DCREAD HTML TO cHtml
MemoWrit('TEST.HTM',cHtml)

RETURN nil

Files:

DCHTML.CH

See Also:

   DCREAD HTML
   dc_html()


DCHTMLBODY

A ccommand for creating the body tag of an HTML document

DCHTMLBODY creates the HTML needed in the BODY tag of an HTML document.<br><br> The command DCHTMLBODY creates an HTML element definition and adds the definition to the array named GETLIST which is later processed by the DC_READHTML() function or by the DCREAD HTML command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD HTML creates all the DC_Html*() objects from the GetList array and then invokes the :writeHtml() method of the topmost parent object to generate the HTML code.<br><br> A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all objects referenced by the GetList array to be released.

Syntax:

DCHTMLBODY                           ;
       [OBJECT <oBody>]              ;
       [STYLE <style>]               ;
       [LINK <link>]                 ;
       [ONLOAD <onload>]             ;
       [VLINK <vlink>]               ;
       [ALINK <alink>]               ;
       [TEXT <textColor>]            ;
       [BGCOLOR <bgcolor>]           ;
       [BGPROPERTIES <bgproperties>] ;
       [LEFTMARGIN <leftmargin>]     ;
       [TOPMARGIN <topmargin>]       ;
       [BACKGROUND <background>]     ;
       [PARENT <oParent>]            ;
       [PARENTID <cPID>]             ;
       [CARGO <xCargo>]              ;
       [HIDE <bHide>]                ;
       [EVAL <bEval>]                ;
       [TITLE <cTitle>]              ;
       [PRE,PRETEXT <bcPreText>]     ;
       [POST,POSTTEXT <bcPostText>]  ;
       [ID <cId>]                    ;
       [GROUP <cGroup>]

Arguments:

STYLE <style> is the name of a *.CSS (cascading style sheet)
file to use as the style of the document.

OBJECT <oBody> is the name of the variable to assign as a
storage place for this object.

PARENT <oParent> is the name of the variable that was
assigned to the parent of this object. If this argument
is not passed then the parent will be the object set with
the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

LINK <link> is the color of hyperlinks which have never been
visited.  Value may be an RGB color value (#XXXXXX),
a standard color name, an RGB 3-element array or a numeric
value defined in GRA.CH.

ALINK <alink> is the color of hyperlinks which has been
clicked. Value may be an RGB color value (#XXXXXX), a standard
color name, an RGB 3-element array or a numeric value
defined in GRA.CH.

VLINK <vlink> is the color of hyperlinks which have been
previously visited.  Value may be an RGB color value (#XXXXXX),
a standard color name, an RGB 3-element array or a numeric
value defined in GRA.CH.

TEXT <textColor> is the color of the text in the body of the
document.  Value may be an RGB color value (#XXXXXX), a
standard color name, an RGB 3-element array or a numeric value
defined in GRA.CH.

BGCOLOR <bgcolor> is the color of the background in the body
of the document.  Value may be an RGB color value (#XXXXXX), a
standard color name, an RGB 3-element array or a numeric value
defined in GRA.CH.

TOPMARGIN <topmargin> and LEFTMARGIN <leftmargin> are the
margins in pixels of the body of the document.

BACKGROUND <background> is a URL pointing to a .JPG or .GIF
image to be used as the background for the body of text.

BGPROPERTIES <bgproperties> if empty allows the background to
scroll.  A value of "fixed" will prevent the background from
scrolling.

ONLOAD <onload> is a Script command that will execute after
the document is loaded.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container of object created by this definition.

PRE,PRETEXT <bcPreHTML> is a character string or a code block
that returns a character string containing any HTML text
that will precede the opening <table> tag in the source
that is written.

POST,POSTTEXT <bcPostHTML> is a character string or a code block
that returns a character string containing any HTML text
that will follow the closing </table> tag in the source
that is written.

HIDE <bHide> is a code block that is evaluated at the
time the :writeHtml() method is called for the class that
supports this command.  If the code block returns a .TRUE.,
then no HTML code will be written.

EVAL <bEval> is a code block that is evaluated after the
object is created in DC_ReadHtml().  A pointer to the
object associated with this command is passed as an
argument to the code block.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETOBJECT() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not used in the HTML output but is simply a description of the
get object which is saved in the GetList.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group.

Notes:

DCHTMLBODY creates an object of the DC_HtmlBody() class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], oMain, cHtml, oBody

DCHTMLMAIN OBJECT oMain

DCHTMLBODY OBJECT oBody ;
     BACKGROUND "http://donnay-software.com/graphics/expback1.gif" ;
     STYLE "\exp18\html\default.css" ;
     PARENT oMain

DCHTML TEXT MemoRead('\exp18\readme.txt') ;
     STYLE 'PRE' ;
     PARENT oBody

DCREAD HTML TO cHtml

MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

DCHTML.CH

See Also:

   DCREAD HTML
   dc_htmlbody()


DCHTMLMAIN

A ccommand for creating the main HTML document

DCHTMLMAIN creates the HTML needed at the start of an HTML document.<br><br> The command DCHTMLMAIN creates an HTML element definition and adds the definition to the array named GETLIST which is later processed by the DC_READHTML() function or by the DCREAD HTML command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD HTML creates all the DC_Html*() objects from the GetList array and then invokes the :writeHtml() method of the topmost parent object to generate the HTML code.<br><br> A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all objects referenced by the GetList array to be released.

Syntax:

DCHTMLMAIN                           ;
       [OBJECT <oMain>]              ;
       [STYLE <cStyle>]              ;
       [PARENT <oParent>]            ;
       [PARENTID <cPID>]             ;
       [CARGO <xCargo>]              ;
       [HIDE <bHide>]                ;
       [EVAL <bEval>]                ;
       [TITLE <cTitle>]              ;
       [PRE,PRETEXT <bcPreText>]     ;
       [POST,POSTTEXT <bcPostText>]  ;
       [ID <cId>]                    ;
       [GROUP <cGroup>]              ;

Arguments:

STYLE <cStyle> is the name of a *.CSS (cascading style sheet)
file to use as the style of the document.

OBJECT <oMain> is the name of the variable to assign as a
storage place for this object.

PARENT <oParent> is the name of the variable that was
assigned to the parent of this object. If this argument
is not passed then the parent will be the object set with
the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container of object created by this definition.

PRE,PRETEXT <bcPreHTML> is a character string or a code block
that returns a character string containing any HTML text
that will precede the opening <table> tag in the source
that is written.

POST,POSTTEXT <bcPostHTML> is a character string or a code block
that returns a character string containing any HTML text
that will follow the closing </table> tag in the source
that is written.

HIDE <bHide> is a code block that is evaluated at the
time the :writeHtml() method is called for the class that
supports this command.  If the code block returns a .TRUE.,
then no HTML code will be written.

EVAL <bEval> is a code block that is evaluated after the
object is created in DC_ReadHtml().  A pointer to the
object associated with this command is passed as an
argument to the code block.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETOBJECT() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not used in the HTML output but is simply a description of the
get object which is saved in the GetList.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group.

Notes:

DCHTMLMAIN creates an object of the DC_HtmlMain() class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], oMain, cHtml, oBody

DCHTMLMAIN OBJECT oMain

DCHTMLBODY OBJECT oBody ;
     BACKGROUND "http://donnay-software.com/graphics/expback1.gif" ;
     STYLE "\exp18\html\default.css" ;
     PARENT oMain

DCHTML TEXT MemoRead('\exp18\readme.txt') ;
     STYLE 'PRE' ;
     PARENT oBody

DCREAD HTML TO cHtml

MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

DCHTML.CH

See Also:

   DCREAD HTML
   DCHTMLMAIN
   dc_htmlmain()


DCHYPERLINK

A command for creating HYPERLINK tags in HTML

DCHYPERLINK is a command for creating HTML href elements for hyperlinks. <br><br>The command DCHYPERLINK creates an HTML element definition and adds the definition to the array named GETLIST which is later processed by the DC_READHTML() function or by the DCREAD HTML command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD HTML creates all the DC_Html*() objects from the GetList array and then invokes the :writeHtml() method of the topmost parent object to generate the HTML code.<br><br>A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all objects referenced by the GetList array to be released.

Syntax:

@ [ <nRow>, <nCol> ] DCHYPERLINK       ;
       [CAPTION,TEXT]                  ;
       [HREF <href>]                   ;
       [METHOD <method>]               ;
       [NAME <name>]                   ;
       [REL <rel>]                     ;
       [REV <rev>]                     ;
       [TARGET <target>]               ;
       [URN <urn>]                     ;
       [PARENT <oParent>]              ;
       [PARENTID <cPID>]               ;
       [OBJECT <oLink>]                ;
       [CARGO <xCargo>]                ;
       [EVAL <bEval>]                  ;
       [PRE,PRETEXT <bcPreText>]       ;
       [POST,POSTTEXT <bcPostText>]    ;
       [HIDE <bHide>]                  ;
       [TITLE <cTitle>]                ;
       [ID <cId>]                      ;
       [GROUP <cGroup>]                ;

Arguments:

<nRow> and <nCol> are the row number and column number of
the table if the parent of this object is a DCTABLE. The
text will be inserted in the cell of the table defined by
the row/column.

CAPTION, TEXT <text> is any html text or element to include
within the <A> tag.  If this argument is not used, then
a child object should be added to the <oLink> parent.

OBJECT <oLink> is the name of the variable to assign as a
storage place for this object.

PARENT <oParent> is the name of the variable that was
assigned to the parent of this object. If this argument
is not passed then the parent will be the object set with
the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container of object created by this definition.

PRE,PRETEXT <bcPreHTML> is a character string or a code block
that returns a character string containing any HTML text
that will precede the opening <table> tag in the source
that is written.

POST,POSTTEXT <bcPostHTML> is a character string or a code block
that returns a character string containing any HTML text
that will follow the closing </table> tag in the source
that is written.

HIDE <bHide> is a code block that is evaluated at the
time the :writeHtml() method is called for the class that
supports this command.  If the code block returns a .TRUE.,
then no HTML code will be written.

EVAL <bEval> is a code block that is evaluated after the
object is created in DC_ReadHtml().  A pointer to the
object associated with this command is passed as an
argument to the code block.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETOBJECT() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not used in the HTML output but is simply a description of the
get object which is saved in the GetList.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group.

HREF <href> is the URL to navigate to when the user clicks on
the text or image underlined.

METHOD <method> is the method of the href.

NAME <name> is the name of the label within the target document.

REL <rel> is the relationship of the source to the target.

REV <rev> is the relationship of the target to the source.

TITLE <title> is a tooltip to display when the mouse is moved
over the hyperlink.

TARGET <target> is the name of the window or frame which is the
target for the returned response.

URN <urn> is the Uniform Resource Name for a referenced document.

Notes:

DCHYPERLINK creates an object of the DC_HtmlHyperLink()class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], cHtml, oLink

DCHYPERLINK HREF "http://donnay-software.com" ;
      OBJECT oLink

DCIMAGE SRC "http://donnay-software.com/graphics/donnay-logo.jpg" ;
      ALT 'Donnay Logo' PARENT oTable ;
      HEIGHT 100 ;
      PARENT oLink

DCREAD HTML TO cHtml

MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

DCHTML.CH

See Also:

   DCREAD HTML
   dc_html()
   dc_readhtml()
   dc_htmlhyperlink()


DCIMAGE

A command for creating IMAGE tags in HTML

DCIMAGE is a command for creating HTML image elements. The command DCIMAGE creates an HTML element definition and adds the definition to the array named GETLIST which is later processed by the DC_READHTML() function or by the DCREAD HTML command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD HTML creates all the DC_Html*() objects from the GetList array and then invokes the :writeHtml() method of the topmost parent object to generate the HTML code.<br><br>A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all objects referenced by the GetList array to be released.

Syntax:

@ [ <nRow>, <nCol> ] DCIMAGE            ;
      [BORDER <border>]                 ;
      [SRC <src>]                       ;
      [DYNSRC <dynsrc>]                 ;
      [LOWSRC <lowsrc>]                 ;
      [START <start>]                   ;
      [USEMAP <usemap>]                 ;
      [WIDTH <width>]                   ;
      [HEIGHT <height>]                 ;
      [LOOP <loop>]                     ;
      [ISMAP]                           ;
      [ALT <alt>]                       ;
      [CONTROLS <controls>]             ;
      [ALIGN <align>]                   ;
      [OBJECT <oImage>]                 ;
      [PARENT <oParent>]                ;
      [PARENTID <cPID>]                 ;
      [HSPACE <vspace>]                 ;
      [VSPACE <hspace>]                 ;
      [CARGO <xCargo>]                  ;
      [HIDE <bHide>]                    ;
      [WHEN <bWhen>]                    ;
      [EVAL <bEval>]                    ;
      [TITLE <cTitle>]                  ;
      [PRE,PRETEXT <bcPreText>]         ;
      [POST,POSTTEXT <bcPostText>]      ;
      [ID <cId>]                        ;
      [GROUP <cGroup>]                  ;

Arguments:

<nRow> and <nCol> are the row number and column number of
the table if the parent of this object is a DCTABLE. The
text will be inserted in the cell of the table defined by
the row/column.

OBJECT <oImage> is the name of the variable to assign as a
storage place for this object.

PARENT <oParent> is the name of the variable that was
assigned to the parent of this object. If this argument
is not passed then the parent will be the object set with
the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

SRC <src> is the URL source of the image to display. This may
may be a character string or an array of 2-character
strings.  If it is an array, the URL in the first element
of the array will be used if the WHEN <bWhen> clause
evaluates to .TRUE. otherwise the second element of the
array will be used.

DYNSRC <dynsrc> (Internet Explorer) is the URL source of an AVI
clip to play.

LOWSRC <lowsrc> is the URL source of the low resolution image
to display while the browser is loading the high resolution
image (for speed in loading).

ALT <alt> is the text to display in the event that the URL for
the image is broken.

USEMAP <usemap> is the name of a map that is created with the
<MAP> tag of HTML.

LOOP (Internet Explorer) will force continuous playing of the
AVI clip.

ALIGN <align> is used to align the image within the body content.
Acceptable values are "top", "middle", "bottom", "texttop",
"absmiddle","baseline" and "absbottom".

START <start> (Internet Explorer) contains options for how to
start the AVI clip.

CONTROLS <controls> (Internet Explorer) is a URL pointing to an
image used as the controls for the AVI player.

BORDER <border> should be set to 0 to eliminate the hyperlink
attribute around the image.

ISMAP will send the coordinates of the mouse when clicked on
the image.

WIDTH <nWidth> is the width in pixels to display the image.
If this argument is not used, then the width will default
to the native width of the image.

HEIGHT <nHeight> is the height in pixels to dislay the
image. If this argument is not used, then the height will
default to the native height of the image.

HSPACE <nHSpace> is the number of pixels of space on the
outside of the image on both the left and right side.

VSPACE <nVSpace> is the number of pixels of space on the
outside of the image on both the top and bottom.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container of object created by this definition.

PRE,PRETEXT <bcPreHTML> is a character string or a code block
that returns a character string containing any HTML text
that will precede the opening <table> tag in the source
that is written.

POST,POSTTEXT <bcPostHTML> is a character string or a code block
that returns a character string containing any HTML text
that will follow the closing </table> tag in the source
that is written.

HIDE <bHide> is a code block that is evaluated at the
time the :writeHtml() method is called for the class that
supports this command.  If the code block returns a .TRUE.,
then no HTML code will be written.

EVAL <bEval> is a code block that is evaluated after the
object is created in DC_ReadHtml().  A pointer to the
object associated with this command is passed as an
argument to the code block.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETOBJECT() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not used in the HTML output but is simply a description of the
get object which is saved in the GetList.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group.

Notes:

DCIMAGE creates an object of the DC_HtmlImage() class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], cHtml, oTable

DCTABLE OBJECT oTable ;
       ROWS 1 COLUMNS 2 BORDER 1

@ 1,1 DCIMAGE SRC "http://donnay-software.com\graphics\donnay-logo.jpg" ;
        ALT 'Donnay Logo' PARENT oTable ;
        HEIGHT 100

@ 1,2 DCIMAGE SRC "http://donnay-software.com\graphics\xb2net.gif" ;
        ALT 'XB2.NET Logo' PARENT oTable ;
      VSPACE 20 ;
      HSPACE 20

DCREAD HTML TO cHtml

MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

DCHTML.CH

See Also:

   DCREAD HTML
   dc_html()
   dc_readhtml()
   dc_htmlimage()


DCINPUT

A command for creating input elements for HTML forms

DCINPUT is a command for creating input tags to be used in HTML forms.<br><br>The command DCINPUT creates an HTML element definition and adds the definition to the array named GETLIST which is later processed by the DC_READHTML() function or by the DCREAD HTML command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD HTML creates all the DC_Html*() objects from the GetList array and then invokes the :writeHtml() method of the topmost parent object to generate the HTML code.<br><br>A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all objects referenced by the GetList array to be released.<br><br>

Syntax:

@ [ <nRow>, <nCol> ] DCINPUT     ;
          [TYPE <ncType>]        ;
          [OBJECT <oInput>]      ;
          [PARENT <oParent>]     ;
          [PARENTID <cPID>]      ;
          [SRC,SOURCE <cSource>] ;
          [HEIGHT <nHeight>]     ;
          [WIDTH <nWidth>]       ;
          [MAXLENGTH <nMaxLength>] ;
          [CHECKED,SELECTED]     ;
          [VALUE <xValue>]       ;
          [LIST <aList>]         ;
          [TABINDEX <nTabIndex>] ;
          [ONFOCUS <cOnFocus>]   ;
          [ONBLUR <cOnBlur>]     ;
          [ONSELECT <cOnSelect>] ;
          [ONCHANGE <cOnChange>] ;
          [ONCLICK <cOnClick>]   ;
          [ACCEPT <cAccept>]     ;
          [ACCESSKEY <cAccessKey>] ;
          [CARGO <xCargo>]       ;
          [HIDE <bHide>]         ;
          [EVAL <bEval>]         ;
          [PRE,PRETEXT]          ;
          [POST,POSTTEXT]        ;
          [TITLE <cTitle>]       ;
          [ID <cId>]             ;
          [GROUP <cGroup>]       ;

Arguments:

<nRow> and <nCol> are the row number and column number of
the table if the parent of this object is a DCTABLE. The
text will be inserted in the cell of the table defined by
the row/column.

OBJECT <oForm> is the name of the variable to assign as a
storage place for this object.

TYPE <ncType> is the type of input element to create:

Type                           Description
------------------------------ ------------------------------
DCHTML_INPUT_TEXT              Text similar to standard GET
  or "text"

DCHTML_INPUT_PASSWORD          Text similar to standard GET
  or "password"                except asterisks mask input

DCHTML_INPUT_CHECKBOX          Logical checkbox
  or 'checkbox'

DCHTML_INPUT_RADIOBUTTON       Radio button
  or 'radio'

DCHTML_INPUT_SUBMITBUTTON      Pushbutton to submit form
  or 'submit'

DCHTML_INPUT_RESETBUTTON       Pushbutton to reset form
  or 'reset'

DCHTML_INPUT_IMAGE             Clickable image (returns coords)
  or 'image'

DCHTML_INPUT_HIDDEN            Hidden variable
  or 'hidden'

DCHTML_INPUT_TEXTAREA          Memo text similar to MLE
  or 'textarea'

DCHTML_INPUT_SELECT            Combo box
  or 'select'

DCHTML_INPUT_BUTTON            Push button
  or 'button'

DCHTML_INPUT_FILE              File Choose Dialog
  or 'file'

CHECKED or SELECTED will be check or select the item.
This applies only to "radio", "checkbox" or "select" items.

MAXLENGTH <nMaxLength> is the maximum amount of text allowed
to be input.  Applies to type "text", "password" and
"textarea".

SIZE <nSize> is the length (in characters) of type "text" or
"password" items.

WIDTH <nWidth> is the width (in characters) of type "textarea"

HEIGHT <nHeight> is the height (in characters) of type
"textarea"

VALUE <xValue> is the current value of the item.  If the
item is a "button", "reset" or "submit" then this will be
the caption of the button.

SRC <cSource> is the URL of the image if the type of input is
an "image".

LIST <aList> is an array of list items for inputs of type
"select".

ONFOCUS <cOnFocus> is a script to run when the item receives
focus.

ONBLUR <cOnBlur> is a script to run when the item loses focus.

ONSELECT <cOnSelect> is a script to run when an item has been
selected.

ONCHANGE <cOnChange> is a script to run when an item has
changed.

ONCLICK <cOnClick> is a script to run when an item has
been clicked with the mouse.

TABINDEX <nTabIndex> is the order in the tab list for this
item.

ACCESSKEY <cAccessKey> assigns an access key to the item.
An access key is a single character from the document
character set.

ACCEPT <cAccept> is the Content Type. (not normally used).

PARENT <oParent> is the name of the variable that was
assigned to the parent of this object. If this argument
is not passed then the parent will be the object set with
the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container of object created by this definition.

PRE,PRETEXT <bcPreHTML> is a character string or a code block
that returns a character string containing any HTML text
that will precede the opening <table> tag in the source
that is written.

POST,POSTTEXT <bcPostHTML> is a character string or a code block
that returns a character string containing any HTML text
that will follow the closing </table> tag in the source
that is written.

HIDE <bHide> is a code block that is evaluated at the
time the :writeHtml() method is called for the class that
supports this command.  If the code block returns a .TRUE.,
then no HTML code will be written.

EVAL <bEval> is a code block that is evaluated after the
object is created in DC_ReadHtml().  A pointer to the
object associated with this command is passed as an
argument to the code block.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETOBJECT() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not used in the HTML output but is simply a description of the
get object which is saved in the GetList.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group.

Notes:

DCINPUT creates an object of the DC_HtmlInput() class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], oHtml, oTable, cHtml, aListItems, cUserId,
      cPassword, lCheck, oForm

cUserId := Space(10)
cPassword := ''
lCheck := .t.
aListItems := { 'Men','Women','Dogs','Cats','Mice','Turkeys' }

DCFORM OBJECT oForm

DCTABLE OBJECT oTable ROWS 10 COLUMNS 2 BORDER 1 PARENT oForm

@ 1,1 DCSAY 'User ID' PARENT oTable
@ 1,2 DCINPUT VALUE cUserId NAME 'Input.Type.Text' ;
      PARENT oTable MAXLENGTH 10

@ 2,1 DCSAY 'Password' PARENT oTable
@ 2,2 DCINPUT TYPE "password" VALUE cPassword ;
      NAME 'Input.Type.PassWord' PARENT oTable MAXLENGTH 10

@ 3,1 DCSAY 'CheckBox' PARENT oTable
@ 3,2 DCINPUT TYPE "checkbox" NAME 'Input.Type.CheckBox' ;
      VALUE lCheck CHECKED PARENT oTable

@ 4,1 DCSAY 'Radio Buttons' PARENT oTable
@ 4,2 DCINPUT TYPE "radio" VALUE 'M' NAME 'Input.Type.RadioButton' ;
      PARENT oTable POST 'Mint<br>'
@ 4,2 DCINPUT TYPE "radio" VALUE 'E' NAME 'Input.Type.RadioButton' ;
      PARENT oTable POST 'Excellent<br>'
@ 4,2 DCINPUT TYPE "radio" VALUE 'G' NAME 'Input.Type.RadioButton' ;
      CHECKED PARENT oTable POST 'Good<br>'
@ 4,2 DCINPUT TYPE "radio" VALUE 'F' NAME 'Input.Type.RadioButton' ;
      PARENT oTable POST 'Fair<br>'
@ 4,2 DCINPUT TYPE "radio" VALUE 'P' NAME 'Input.Type.RadioButton' ;
      PARENT oTable POST 'Poor<br>'

@ 5,1 DCSAY 'Submit Button' PARENT oTable
@ 5,2 DCINPUT TYPE "submit" VALUE 'Hit Me!' ;
      NAME 'Input.Type.Submit' PARENT oTable

@ 6,1 DCSAY 'Reset Button' PARENT oTable
@ 6,2 DCINPUT TYPE "reset" VALUE 'Reset Form!' ;
      NAME 'Input.Type.Reset' PARENT oTable

@ 7,1 DCSAY 'Image' PARENT oTable
@ 7,2 DCINPUT TYPE "image" SRC '\exp18\images\express2.gif' ;
      NAME 'Input.Type.Image' PARENT oTable

@ 8,1 DCSAY 'ComboBox' PARENT oTable
@ 8,2 DCINPUT TYPE "select" ;
      LIST aListItems ;
      NAME 'Input.Type.Select' PARENT oTable

@ 9,1 DCSAY 'File' PARENT oTable
@ 9,2 DCINPUT TYPE "file" ;
      SIZE 40 ;
      MAXLENGTH 100 ;
      NAME 'Input.Type.File' PARENT oTable

@10,1 DCSAY 'Read Me' PARENT oTable
@10,2 DCINPUT ;
         TYPE DCHTML_INPUT_TEXTAREA ;
         WIDTH 60 HEIGHT 20 ;
         NAME 'Input.Type.TextArea' ;
         VALUE {||MemoRead('\exp18\samples\html\readme.txt')} ;
         PARENT oTable

DCREAD HTML TO cHtml
MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

DCHTML.PRG

See Also:

   DCREAD HTML
   dc_htmlinput()
   dc_readhtml()


DCLDEBUG

Send debug information to a debugging Log File

DCLDEBUG is used to send data to a log file when debugging GUI applications. <br><br> A list of expressions may be included and the output of each expression will be displayed on a new line in the window.<br><br>

Syntax:

 DCLDEBUG <xExpr1> [ ; <xExprN> ]

Arguments:

<xExpr1> through <xExprN> is any expression.

Notes:

DC_DebugQoutAppendBlock() is a get-set function used to setupadditional information to append to each debug line.

Examples:

 #include "dcdialog.ch"

 USE COLLECT NEW SHARED

 DCLDEBUG Alias(), RecCount()

Files:

DCDIALOG.CH

See Also:

   DCQDEBUG
   DCLDEBUGOFF
   DCBDEBUG


DCLDEBUGOFF

Send debug information to a debugging Log File

DCLDEBUGOFF is used to send data to a log file when debugging GUI applications. <br><br> A list of expressions may be included and the output of each expression will be displayed on a new line in the window.<br><br> DCLDEBUGOFF is similar to DCLDEBUG except it will not echo the expression.<br><br>

Syntax:

 DCLDEBUGOFF <xExpr1> [ ; <xExprN> ]

Arguments:

<xExpr1> through <xExprN> is any expression.

Notes:

DC_DebugQoutAppendBlock() is a get-set function used to setupadditional information to append to each debug line.

Examples:

 #include "dcdialog.ch"

 USE COLLECT NEW SHARED

 DCLDEBUGOFF Alias(), RecCount()

Files:

DCDIALOG.CH

See Also:

   DCQDEBUG
   DCLDEBUG


DCLDEBUGOFFQUIET

Send debug information to a debugging Log File

DCLDEBUGOFFQUIET is used to send data to a log file when debugging GUI applications. <br><br> A list of expressions may be included and the output of each expression will be displayed on a new line in the window.<br><br> DCLDEBUGOFFQUIET is similar to DCLDEBUG except it will not echo the expression or the callstack information.<br><br><br><br>

Syntax:

 DCLDEBUGOFFQUIET <xExpr1> [ ; <xExprN> ]

Arguments:

<xExpr1> through <xExprN> is any expression.

Notes:

DC_DebugQoutAppendBlock() is a get-set function used to setupadditional information to append to each debug line.

Examples:

 #include "dcdialog.ch"

 USE COLLECT NEW SHARED

 DCLDEBUGOFFQUIET Alias(), RecCount()

Files:

DCDIALOG.CH

See Also:

   DCQDEBUG
   DCLDEBUG


DCLDEBUGQUIET

Send debug information to a debugging Log File

DCLDEBUGQUIET is used to send data to a Log File when debugging GUI applications. <br><br> A list of expressions may be included and the output of each expression will be displayed on a new line in the window.<br><br> DCLDEBUGQUIET is similar to DCLDEBUG except it will not echo the callstack information.<br><br><br><br>

Syntax:

 DCLDEBUGQUIET <xExpr1> [ ; <xExprN> ]

Arguments:

<xExpr1> through <xExprN> is any expression.

Notes:

DC_DebugQoutAppendBlock() is a get-set function used to setupadditional information to append to each debug line.

Examples:

 #include "dcdialog.ch"

 USE COLLECT NEW SHARED

 DCLDEBUGQUIET Alias(), RecCount()

Files:

DCDIALOG.CH

See Also:

   DCQDEBUG
   DCLDEBUG


DCLIST

A command for creating lists in HTML

DCLIST is a command for creating HTML lists elements. The list type may be ordered, unordered, directory, menu or definition. <br><br>The command DCLIST creates an HTML element definition and adds the definition to the array named GETLIST which is later processed by the DC_READHTML() function or by the DCREAD HTML command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD HTML creates all the DC_Html*() objects from the GetList array and then invokes the :writeHtml() method of the topmost parent object to generate the HTML code.<br><br>A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all objects referenced by the GetList array to be released.<br><br>

Syntax:

@ [ <nRow>,<nCol> ] DCLIST       ;
          [TYPE <nType>]         ;
          [ITEMLIST <aList>]     ;
          [ITEMTYPE <nListType>] ;
          [STYLE,FONT <cStyle>]  ;
          [COMPACT]              ;
          [OBJECT <oList>]       ;
          [PARENT <oParent>]     ;
          [PARENTID <cPID>]      ;
          [CARGO <xCargo>]       ;
          [HIDE <bHide>]         ;
          [EVAL <bEval>]         ;
          [PRE,PRETEXT]          ;
          [POST,POSTTEXT]        ;
          [TITLE <cTitle>]       ;
          [ID <cId>]             ;
          [GROUP <cGroup>]       ;

Arguments:

<nRow> and <nCol> are the row number and column number of
the table if the parent of this object is a DCTABLE. The
text will be inserted in the cell of the table defined by
the row/column.

TYPE <type> is the type of the list:

"ul" or DCHTML_LIST_UNORDERED creates an unordered list.
"ol" or DCHTML_LIST_ORDERED creates an ordered list.
"dir" or DCHTML_LIST_DIRECTORY creates a directory list.
"menu" or DCHTML_LIST_MENU creates a menu list.
"dl" or DCHTML_LIST_DEFINITION creates a definition list.

ITEMLIST <aList> is an array of items to be displayed in
the list.  Each item must be a character string.  If no
array of items is used then the list of items consists of
child objects of the type DC_HtmlListItem() or DCLISTITEM.

ITEMTYPE <nListType> is the type of each list item.  This
has a different meaning for different types of lists.

Ordered lists:

"A" will order each item in capital letters.
"a" will order each item in lower case letters.
"I" wlll order each item in capital Roman numerals.
"i" wlll order each item in lower case Roman numerals.
"1" will order each item in Arabic numerals.

Unordered, Directory, and Menu lists:

"disc" will display a disc image in front of the item
"circle" will display a circle image in front of the item
"square" will display a square image in front of the item

COMPACT will tell the browser to reduce the indentation
and number of spaces between the sequence numbers and the
list items, or both.

STYLE <cStyle> is the style tag to wrap around the text.  For
example STYLE "H3" will create the following source:
<H3><bcText></H3>.

OBJECT <oList> is the name of the variable to assign as a
storage place for this object.

PARENT <oParent> is the name of the variable that was
assigned to the parent of this object. If this argument
is not passed then the parent will be the object set with
the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container of object created by this definition.

PRE,PRETEXT <bcPreHTML> is a character string or a code block
that returns a character string containing any HTML text
that will precede the opening <table> tag in the source
that is written.

POST,POSTTEXT <bcPostHTML> is a character string or a code block
that returns a character string containing any HTML text
that will follow the closing </table> tag in the source
that is written.

HIDE <bHide> is a code block that is evaluated at the
time the :writeHtml() method is called for the class that
supports this command.  If the code block returns a .TRUE.,
then no HTML code will be written.

EVAL <bEval> is a code block that is evaluated after the
object is created in DC_ReadHtml().  A pointer to the
object associated with this command is passed as an
argument to the code block.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETOBJECT() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not used in the HTML output but is simply a description of the
get object which is saved in the GetList.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group.

Notes:

DCLIST creates an object of the DC_HtmlList() class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], oTable, cHtml, oList1, oList2, aListItems

aListItems := { 'Men','Women','Dogs','Cats','Mice','Turkeys' }

DCTABLE OBJECT oTable ROWS 1 COLUMNS 2

@ 1, 1 DCLIST OBJECT oList1 ;
     TYPE 'ol' ;
     ITEMLIST aListItems ;
     ITEMTYPE 'i' ;
     PARENT oTable

@ 1, 2 DCLIST OBJECT oList2 ;
     TYPE 'ul' ;
     PARENT oTable

FOR i := 1 TO Len(aListItems)
  DCLISTITEM aListItems[i] ;
  PARENT oList2 ;
  TYPE 'circle'
NEXT

DCREAD HTML to cHtml

MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

DCHTML.PRG

See Also:

   DCREAD HTML
   dc_htmllist
   dc_htmllistitem()
   dc_readhtml()


DCLISTITEM

A command for creating list items in HTML

DCLISTITEM is a command for creating HTML lists items to be added to a DCLIST parent.<br><br>The command DCLISTITEM creates an HTML element definition and adds the definition to the array named GETLIST which is later processed by the DC_READHTML() function or by the DCREAD HTML command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD HTML creates all the DC_Html*() objects from the GetList array and then invokes the :writeHtml() method of the topmost parent object to generate the HTML code.<br><br>A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all objects referenced by the GetList array to be released.<br><br>

Syntax:

DCLISTITEM                       ;
          [TYPE <nType>]         ;
          [STYLE,FONT <cStyle>]  ;
          [OBJECT <oItem>]       ;
          [VALUE <value>]        ;
          [PARENT <oParent>]     ;
          [PARENTID <cPID>]      ;
          [CARGO <xCargo>]       ;
          [HIDE <bHide>]         ;
          [EVAL <bEval>]         ;
          [PRE,PRETEXT]          ;
          [POST,POSTTEXT]        ;
          [TITLE <cTitle>]       ;
          [ID <cId>]             ;
          [GROUP <cGroup>]       ;

Arguments:

TYPE <nListType> is the type of each list item.  This
has a different meaning for different types of lists.
The type of list is defined by the DCLIST parent.

Ordered lists:

"A" will order each item in capital letters.
"a" will order each item in lower case letters.
"I" wlll order each item in capital Roman numerals.
"i" wlll order each item in lower case Roman numerals.
"1" will order each item in Arabic numerals.

Unordered, Directory, and Menu lists:

"disc" will display a disc image in front of the item
"circle" will display a circle image in front of the item
"square" will display a square image in front of the item

STYLE <cStyle> is the style tag to wrap around the text.  For
example STYLE "H3" will create the following source:
<H3><bcText></H3>.

OBJECT <oItem> is the name of the variable to assign as a
storage place for this object.

PARENT <oParent> is the name of the variable that was
assigned to the parent of this object. If this argument
is not passed then the parent will be the object set with
the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container of object created by this definition.

PRE,PRETEXT <bcPreHTML> is a character string or a code block
that returns a character string containing any HTML text
that will precede the opening <table> tag in the source
that is written.

POST,POSTTEXT <bcPostHTML> is a character string or a code block
that returns a character string containing any HTML text
that will follow the closing </table> tag in the source
that is written.

HIDE <bHide> is a code block that is evaluated at the
time the :writeHtml() method is called for the class that
supports this command.  If the code block returns a .TRUE.,
then no HTML code will be written.

EVAL <bEval> is a code block that is evaluated after the
object is created in DC_ReadHtml().  A pointer to the
object associated with this command is passed as an
argument to the code block.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETOBJECT() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not used in the HTML output but is simply a description of the
get object which is saved in the GetList.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group.

VALUE <value> lets you change the number of a specific list
item and those that follow it.  This is valid only for
ordered lists.  Example <value> = 9 will change the order
numbering to start at 9.

Notes:

DCLISTITEM creates an object of the DC_HtmlListItem() class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], oTable, cHtml, oList1, oList2, aListItems

aListItems := { 'Men','Women','Dogs','Cats','Mice','Turkeys' }

DCTABLE OBJECT oTable ROWS 1 COLUMNS 2

@ 1, 1 DCLIST OBJECT oList1 ;
     TYPE 'ol' ;
     ITEMLIST aListItems ;
     ITEMTYPE 'i' ;
     PARENT oTable

@ 1, 2 DCLIST OBJECT oList2 ;
     TYPE 'ul' ;
     PARENT oTable

FOR i := 1 TO Len(aListItems)
  DCLISTITEM aListItems[i] ;
  PARENT oList2 ;
  TYPE 'circle'
NEXT

DCREAD HTML to cHtml

MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

DCHTML.PRG

See Also:

   DCREAD HTML
   dc_htmllist
   dc_htmllistitem()
   dc_readhtml()


DCMENUBAR

Create a MENUBAR object for displaying with Text/GUI reader

The command DCMENUBAR creates a new MenuBar object and adds the object to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> DCMENUBAR is used with the DCSUBMENU command to add pull-down menus to MenuBar.<br><br> DCMENUBAR objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCRADIO, @..DCPUSHBUTTON, @..DCMULTILINE, DCTOOBAR, etc.<br><br>

Syntax:

DCMENUBAR <oMenuBar> ;
    [PARENT <oParent>] ;
    [PARENTID <cParentId>] ;
    [PREEVAL <bPreEval>] ;
    [EVAL <bEval>] ;
    [TITLE <cTitle>] ;
    [CARGO <xCargo>] ;
    [ID <cId>] ;
    [TITLE <cTitle>] ;
    [GROUP <cGroup>] ;
    [OWNERDRAW] ;
    [MENUBARFONT <cMenuBarFont>] ;
    [MENUBARCOLOR <anMenuBarColorFG>, <anMenuBarColorBG>] ;
    [SUBFGCOLOR <anSubFGColor>] ;
    [SUBBGCOLOR <anSubBGColor>] ;
    [SUBBARCOLOR <anSubBarColorFG>,<anSubBarColorBG>] ;
    [SUBBARFONT <cSubBarFont>] ;
    [SUBITEMFONT <cSubItemFont>] ;
    [SUBCHECKCHAR <cSubCheckChar>] ;
    [SUBCHECKFONT <cSubCheckFont>] ;
    [BEGINMENU <bBeginMenu>] ;
    [ENDMENU <bEndMenu>] ;
    [ITEMMARKED <bItemMarked>] ;
    [ITEMSELECTED <bItemSelected>] ;
    [BARBITMAP <ocnBarBitmap>] ;
    [MESSAGEBOXATTACHED]

Arguments:

<oMenuBar> is the name of the variable to assign as a storage
place for the menu bar.

PARENT <oParent> is the name of the variable that was
assigned to the parent DIALOG for this MenuBar.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

OWNERDRAW will cause all submenus to be painted with a more
eye-appealling design, including a vertical bar on the left side
of each submenu with a vertically painted caption and user-defined
colors.  This option is available only when using Xbase++ 1.9 or
later.

MENUBARFONT <cMenuBarFont> is the font of the menubar items when
the OWNERDRAW option is used.

MENUBARCOLOR <anMenuBarColorFG>, <anMenuBarColorBG> is the foreground
and background color of the menubar when the OWNERDRAW option is
used.

SUBBARFONT <cSubBarFont> is the font compound name to use for all
text in the vertical bar when the OWNERDRAW option is used.

SUBFGCOLOR <anSubColorFG> is the foreground color of the pull
down menus when the OWNERDRAW option is used.  This may be a numeric
GRA_CLR_* value or an array of 3 numeric values for RGB.

SUBBGCOLOR <anSubColorBG> is the background color of the pull
down menus when the OWNERDRAW option is used.  This may be a numeric
GRA_CLR_* value or an array of 3 numeric values for RGB.

SUBBARCOLOR <anSubBarColorFG>, <anSubBarColorBG> are the foreground
and background colors of the vertical bar when the OWNERDRAW option
is used.  These may be a numeric GRA_CLR_* value or an array of
3 numeric values for RGB.

SUBCHECKFONT <cSubCheckFont> is the font to use for the check
character of Submenus when the OWNERDRAW option is used.
Default is 10.Marlett

SUBCHECKCHAR <cSubCheckChar> is the character to use when a
menu item is checked and the OWNERDRAW option is used.
Default is 'b'.

Note: If color options are not used, then they are defaulted for
all menus with DC_XbpMenuConfig().

The BEGINMENU <bBeginMenu> code block is evaluated when a user activates a
menu and starts with the menu selection. {| uNIL1, uNIL2, self | ... }

The ENDMENU <bEndMenu> code block is evaluated when a user has selected a
menu item or aborted menu selection. {| uNIL1, uNIL2, self | ... }

The ITEMMARKED <bItemMarked> code block is evaluated when a menu item in a
menu has been highlighted. This can be used to display additional
information associated with a particular menu item, for example.
{| nItemIndex, uNIL, self | ... }

The ITEMSELECTED <bItemSelected> code block is evaluated when a menu item in a
menu has been selected. This occurs after the user clicks the left
mouse button on the menu item, presses the Return key when the
item is highlighted, or presses the shortcut key combination. This
event is only generated if the selected menu item does not contain
a code block. If it does not contain a code block, the callback
code block or method of the menu object is executed. The first
parameter  <nItemIndex> contains the ordinal position of the selected
menu item. {| nItemIndex, uNIL, self | ... }

SUBITEMFONT <cSubItemFont> is the default font for all subitems of this submenu.
This parameter is ignored if not using the OWNERDRAW option.

BARBITMAP <ocnBarBitMap> is the name of an icon, bitmap, resource or
XbpIcon or XbpBitmap object to use to tile across the unused area of
the menubar where there are no menu items.  See sample program:
.\samples\menu\msgbox.prg.

MESSAGEBOXATTACHED will create a messagebox that is attached to
pull-down menus.  This provides a better view of menu messages.
See sample program: .\samples\menu\msgbox2.prg.

Notes:

The object created by DCMENUBAR is an object of the XbpMenuBar() class, therefore it can be manipulated with any iVar or method supported by XbpMenuBar().

Examples:

/*
This example displays a dialogue box with two tab pages
and a menu with 3 submenus:  File, Edit, Util.
*/

#include "dcdialog.ch"
#include "appevent.ch"

PROCEDURE Xtest()

LOCAL GetList := {}, oFileMenu, oMenuBar, oEditMenu, oMemo, oUtilMenu, ;
      cMemo

USE COLLECT

cMemo := COLLECT->memo

@ 0,0 DCMULTILINE cMemo SIZE 70,7 FONT "10.Courier.Bold"

/* ---- Menu ---- */

DCMENUBAR oMenuBar

DCSUBMENU oFileMenu PROMPT "&File" PARENT oMenuBar

DCMENUITEM "&Open a File" PARENT oFileMenu ;
            ACTION {||Msgbox('OpenFile')} ;

DCMENUITEM "&Close File" PARENT oFileMenu ;
            ACTION {||Msgbox('CloseFile')}

DCMENUITEM "&Pack File" PARENT oFileMenu ;
            ACTION {||Msgbox('Packfile')}

DCSUBMENU oEditMenu PROMPT "&Edit" PARENT oMenuBar

DCMENUITEM "&Next Record" PARENT oEditMenu ;
            ACTION {||dbSkip(), ;
                      cMemo := COLLECT->memo,;
                      DC_GetRefresh(GetList)} ;
            ACCELKEY xbeK_ALT_N ;
            WHEN {||!Eof()}

DCMENUITEM "&Previous Record" PARENT oEditMenu ;
            ACTION {||dbSkip(-1), ;
                      cMemo := COLLECT->memo,;
                      DC_GetRefresh(GetList)} ;
            ACCELKEY xbeK_ALT_P ;
            WHEN {||!Bof()}

DCMENUITEM "&Top of File" PARENT oEditMenu ;
            ACTION {||dbGoTop(), ;
                      cMemo := COLLECT->memo,;
                      DC_GetRefresh(GetList)} ;
            ACCELKEY xbeK_ALT_T

DCMENUITEM "&Bottom of File" PARENT oEditMenu ;
            ACTION {||dbGoBottom(), ;
                      cMemo := COLLECT->memo, ;
                      DC_GetRefresh(GetList)} ;
            ACCELKEY xbeK_ALT_B

DCSUBMENU oUtilMenu PROMPT "&Util" PARENT oMenuBar

DCMENUITEM "Copy File" PARENT oUtilMenu ;
            ACTION {||Msgbox('CopyFile')}

DCMENUITEM "Move File" PARENT oUtilMenu ;
            ACTION {||Msgbox('MoveFile')}

DCREAD GUI ;
   TITLE 'Menu Demo' ;
   FIT ;
   ADDBUTTONS

RETURN

Files:

DCDIALOG.CH

See Also:

   dc_xbpmenuconfig()
   DCSUBMENU
   DCMENUITEM


DCMENUITEM

Add Item to SUBMENU object for displaying with Text/GUI reader

The command DCMENUITEM creates a new Menu Item object and adds the object to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> DCMENUITEM is used with the DCSUBMENU command to add menu items to a pull-down menu.

Syntax:

DCMENUITEM <cPrompt> ;
    [PARENT <oParent>] ;
    [PARENTID <cParentId>] ;
    [CHECKED] ;
    [CHECKWHEN <bCheckWhen>] ;
    [SEPARATOR] ;
    [STYLE <nStyle>] ;
    [ATTRIBUTE <nAttr>] ;
    [WHEN <bWhen>] ;
    [ACCELKEY <nAccelKey>] ;
    [ACTION <bAction>] ;
    [HELPCODE <cHelpCode>] ;
    [CARGO <xCargo>] ;
    [ID <cId>] ;
    [PRESENTATION <aPres>] ;
    [PREEVAL <bPreEval>] ;
    [EVAL <bEval>] ;
    [ID <cId>] ;
    [TITLE <cTitle>] ;
    [GROUP <cGroup>] ;
    [MESSAGE <cbMsg> [INTO <oMsgBox>]] ;
    [LOCK <cLock>] ;
    [PROTECT <bProtect>] ;
    [BITMAP <nBmUnChecked> [, <nBmChecked>] ] ;
    [COLUMNBREAK]

Arguments:

PROMPT <bcPrompt> is the caption to assign to this menu item.
The caption may be a character string, a resource number for
a bitmap, an XbpBitMap() object another XbpMenu() object,
a NIL (for separator bars), or a code block.  If the caption
is a character string, it may include a Tilde (~) character to
define the hot-key for the item like so: "Save ~Changes". If
<bcPrompt> is a code-block, then it must return a character
string, a resource number or an XbpMenu() object.  This code
block will be evaluated whenever the function DC_GetRefresh()
or DC_GetWhen() is called.

ACTION <bAction> is a code block that gets evaluated when
the menu item is selected.

PARENT <oParent> is the name of the variable that was
assigned to the parent SubMenu for this Menu Item.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

INDEX <nIndex> is a variable name to store the index number
that is assigned to this item when it is created.

CHECKED will cause a check mark to appear next to the menu
item.  This option is ignored if a <nAttr> parameter is used.

CHECKWHEN <bWhen> is a code block that is evaluated in the event
loop. This code block must return a logical value.  If the value
returned is .FALSE. then the item will be unchecked. If the
value returned is .TRUE. then the item will be checked. The
parent DCSUBMENU object is passed as a parameter to the code
block.

SEPARATOR is used only if this is a menu separator bar rather
than a selectable item.  Do not include a PROMPT.  All other
parameters are ignored.  This option is ignored if a <nStyle>
parameter is used.

STYLE <nStyle> is a list of XBPMENUBAR_MIS_* numbers defined
in XBP.CH.  These options are summed together.

ATTRIBUTE <nAttr> is a list of XBPMENUBAR_MIA_* numbers defined
in XBP.CH.  These options are summed together.

  XBPMENUBAR_MIA_NODISMISS  Menu is not closed after selection
  XBPMENUBAR_MIA_FRAMED     Menu item is framed
  XBPMENUBAR_MIA_CHECKED    Menu item has a check mark
  XBPMENUBAR_MIA_DISABLED   Menu item is not available
  XBPMENUBAR_MIA_HILITED    Menu item is displayed highlighted

HELPCODE <cHelp> is a character string that is passed to the
DC_HelpF1() function if F1 is pressed when the mouse is placed
over the menu item.  The help code is used by the Help system to
for specific context-help.

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the Button object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the item will be disabled and grayed.
If the value returned is .TRUE. then the item will be enabled.
The parent DCSUBMENU object is passed as a parameter to the
code block.

ID <cID> is a unique 8-character ID to assign to this menu
item.  This is used to allow users to assign a menu item as
"default" by pressing a special key.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader..

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

ACCELKEY <nAccelKey> is a numeric "hot-key" assignment that will
activate the menu item when the hot-key is pressed.  The key
must be a valid key with the prefix xbeK_*.  These keys are
defined in APPEVENT.CH.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

MESSAGE <bcMsg> is the message you want to display in the
message area of the dialogue screen defined by the DCMESSAGEBOX
command when the mouse is passed over the menu item.  Optionally,
INTO <oMsgBox> will designate which message box to display the
message into. If the INTO clause is not used, then the last
message box in the GetList is the default.  <oMsgBox> may also
be any object that supports the :setCaption() method.  <bcMsg>
may be a code block that returns a character value.

LOCK <cLock> is a lock code to assign to this menu item. Lock
codes are any character string up to 5 characters in length.
To gain access to a menu item, a logged on user must own a key
of the same name as the lock or a master key to the lock.  The
function DC_ReadGuiMenuAccess() must be called prior to calling
DC_ReadGui() or using any DCREAD GUI command in which the Getlist
contains menu items with locks.  DC_ReadGuiMenuAccess() is passed
a comma-delimited character string containing the set of keys
owned by the logged on user.  In a typical application, this
function should be called immediately after the logon of a new
user and the users predefined keylist passed to the function.

 Example: DC_ReadGuiMenuAccess('ABC,K*,XY*')
 This key list will allow access to any menu items that have
 no locks or to menu items locked with 'ABC', 'K*' or 'XY*'
 To give access to all menu locks assign the key "*****'.

If a menu item is locked and the user does not own a key, the
menu item will not be displayed in the menu.

PROTECT <bProtect> is a code block to evaluate which protects
this menu item.  The code block must return a logical value.  If
the value returned is .TRUE. then the menu item will not be
included in the menu.

BITMAP is used to define a bitmap that will be displayed to the
left of the menu item prompt.  <nBmUnChecked> and <nBmChecked>
are the numerical resource numbers of bitmaps that have been
linked into the .EXE and define the bitmaps to be used when the
menu items is checked and unchecked respectively.  If only one
argument is passed then that bitmap will be used for both
checked and unchecked items.

  NOTE: This clause will not function if the menuitem is at
        any level lower than a child of a main submenu.  For
        example, menuitems that are children of sub-sub-menus
        cannot have a bitmap.

COLUMNBREAK causes successive menu items to appear in a new
column of the drop-down or popup menu. Look at the sample
program in the .\SAMPLES\MENU directory.

Notes:

The object created by DCMENUITEM is an object of the XbpMenu() class, therefore it can be manipulated with any iVar or method supported by XbpMenu().

Examples:

/*
This example displays a dialogue box with two tab pages
and a menu with 3 submenus:  File, Edit, Util.
*/

#include "dcdialog.ch"
#include "appevent.ch"

PROCEDURE Xtest()

LOCAL GetList := {}, oFileMenu, oMenuBar, oEditMenu, oMemo, oUtilMenu, ;
      cMemo

USE COLLECT

cMemo := COLLECT->memo

@ 0,0 DCMULTILINE cMemo SIZE 70,7 FONT "10.Courier.Bold"

/* ---- Menu ---- */

DCMENUBAR oMenuBar

DCSUBMENU oFileMenu PROMPT "&File" PARENT oMenuBar

DCMENUITEM "&Open a File" PARENT oFileMenu ;
            ACTION {||Msgbox('OpenFile')} ;

DCMENUITEM "&Close File" PARENT oFileMenu ;
            ACTION {||Msgbox('CloseFile')}

DCMENUITEM "&Pack File" PARENT oFileMenu ;
            ACTION {||Msgbox('Packfile')}

DCSUBMENU oEditMenu PROMPT "&Edit" PARENT oMenuBar

DCMENUITEM "&Next Record" PARENT oEditMenu ;
            ACTION {||dbSkip(), ;
                      cMemo := COLLECT->memo,;
                      DC_GetRefresh(GetList)} ;
            ACCELKEY xbeK_ALT_N ;
            WHEN {||!Eof()}

DCMENUITEM "&Previous Record" PARENT oEditMenu ;
            ACTION {||dbSkip(-1), ;
                      cMemo := COLLECT->memo,;
                      DC_GetRefresh(GetList)} ;
            ACCELKEY xbeK_ALT_P ;
            WHEN {||!Bof()}

DCMENUITEM "&Top of File" PARENT oEditMenu ;
            ACTION {||dbGoTop(), ;
                      cMemo := COLLECT->memo,;
                      DC_GetRefresh(GetList)} ;
            ACCELKEY xbeK_ALT_T

DCMENUITEM "&Bottom of File" PARENT oEditMenu ;
            ACTION {||dbGoBottom(), ;
                      cMemo := COLLECT->memo, ;
                      DC_GetRefresh(GetList)} ;
            ACCELKEY xbeK_ALT_B

DCSUBMENU oUtilMenu PROMPT "&Util" PARENT oMenuBar

DCMENUITEM "Copy File" PARENT oUtilMenu ;
            ACTION {||Msgbox('CopyFile')}

DCMENUITEM "Move File" PARENT oUtilMenu ;
            ACTION {||Msgbox('MoveFile')}

DCREAD GUI ;
   TITLE 'Menu Demo' ;
   FIT ;
   ADDBUTTONS

RETURN

Files:

DCDIALOG.CH

See Also:

   DCSUBMENU
   dc_readguimenuaccess()


DCMSGBOX

Display an array of messages in a window

DCMSGBOX is used to display a set of message lines in a window. This command is an easy-to-use front end to the function DC_MsgBox().

Syntax:

DCMSGBOX <list,...>              ;
         [TITLE <cTitle>]        ;
         [TIMEOUT <nSeconds>]    ;
         [YESNO]                 ;
         [TO <lOutput>]          ;
         [FONT <cFont>]          ;
         [BUTTONS <aButtons>]    ;
         [CHOICE @<nChoice>]     ;
         [EVAL <bEval>]          ;
         [ICON <nIcon>]          ;
         [NORESTORE]             ;
         [ALWAYSONTOP]           ;
         [COLOR <nFG>, [<nBG>]]
  ;
         [BUTTSIZE <aButtSize>]  ;
         [HORIZONTAL]            ;
         [OWNER <oOwner>]

Arguments:

<list,...> is a comma-delimited list of message lines.

TITLE <cTitle> is the title to place at the top of the message
box.

TIMEOUT <nSeconds> will display the box for a specified number
of seconds or until a key is hit.

YESNO will display YES / NO menu items below the message text.

CHOICE @<nChoice> : 1 will default to YES (default),  2 will
default to NO.  If passed by reference and an array of <aButtons>
is also passed, then the value returned will be equivalent to
the menu item selected.

BUTTONS <aButtons> - An array of menu buttons to choose from.  The
number of the selected item will be returned in the <@nChoice>
variable.  This is a single-dimensional array of captions for the
buttons.

TO <lOutput> is a logical variable to store the result of the
message box when using the YESNO clause.  If the operator selects
YES then <lOutput> will be .TRUE., otherwise it will be .FALSE.

HOTKEY @<cHotKey> - An optional parameter to return the value of
the high-lighted letter in the selected menu item when using
DCMSGBOX with an array of menu buttons.  This must be a variable,
passed by reference, in which to store a character value.

FONT <cFont> is the font to use for the message text.  This must
conform to standard font declarations used with the
:setFontCompoundName() method of XbpStatic().

EVAL <bEval> is a code block to evaluate after the Message box
is created.  The Messsage box dialog object is passed to the
code block.

ICON <nIcon> is the icon to use in the message box text area.
The default is XBPSTATIC_SYSICON_ICONQUESTION when the YESNO clause
is used otherwise it is XBPSTATIC_SYSICON_ICONINFORMATION.

NORESTORE overrides the setting of DC_AutoRestoreWindow().

ALWAYSONTOP forces the window to stay on top of all other
application windows.

COLOR <nFG>, <nBG> is the foreground and background color of
the text. The default color is set by the DC_MsgBoxColor() get-set
function.

BUTTSIZE <nButtonWidth>, <nButtonHeight> is the width and height,
in pixels, of the buttons created with the BUTTONS clause,
otherwise the buttons will be sized to the longest caption.

HORIZONTAL will create the buttons horizontally instead of
vertically.

OWNER <oOwner> is the owner of the message box. If the owner
parameter is not used, the message box will center in the
object returned by the SetAppWindow() function, otherwise it
will center on the owner.

Examples:

// Example 1

 PROCEDURE Xtest( )

 DCMSGBOX ;
  'This selection will permanently remove all', ;
  'deleted records.  Continue?' ;
  YESNO ;
  FONT '12.Arial Bold' ;
  TO lOk

 IF lOk
   PACK
 ENDIF

 RETURN

// Example 2

FUNCTION Xtest2()

LOCAL nChoice := 2

DCMSGBOX 'There was an error when trying to',    ;
         'save the file to disk',                ;
         'Please choose a corrective action.'    ;
         TITLE "Save Error!"                     ;
         FONT "10.Arial Bold"                    ;
         BUTTONS {'~Quit the Program',           ;
                  '~Format the Hard Drive',      ;
                  '~Get a beer'}                 ;
         CHOICE @nChoice

IF nChoice = 1
  QUIT
ELSEIF nChoice = 2
  // pray
ELSEIF nChoice = 3
  DCMSGBOX "I will meet you a O'Learys"
ENDIF

RETURN nil

Files:

DCDIALOG.CH

See Also:

   dc_alert()
   dc_menupull()
   dc_msgbox()
   dc_msgboxescape()
   dc_msgboxcolor()


DCMXADDBUTTON

Add an MXPUSHBUTTON to a ToolBar

The command DCMXADDBUTTON creates a new MxPushButton object and adds the object to the array named GETLIST which is later processed by the DC_READGETS() function or by the DCREAD command. DCMXADDBUTTON is used with DCTOOLBAR to add a PushButton to the toolbar. Each button is automatically placed in the next open place on the previously declared ToolBar. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> @..DCMXADDBUTTON objects can be combined with any objects that that use the DCDIALOG system, such as @..DCSAY..GET, @..DCRADIO, @..DCMULTILINE, @..DCCHECKBOX or @..DCTABPAGE.<br><br> @..DCMXADDBUTTON objects are derived from Joe Carrick's MxPushButton class. Each object may contain up to 3 captions of type text, bitmap or icon.

Syntax:

See @ DCMXPUSHBUTTON.
The arguments are the same except that the row and column
arguments are not needed.

Arguments:

See @ DCMXPUSHBUTTON.

Notes:

The object created by @ DCMXPUSHBUTTON is an object of the MxPushButton() class, therefore it can be manipulated with any iVar or method supported by MxPushButton() class.

Use the clause CARGO 'CANCEL' if the pushbutton is to be used to exit a dialog without testing validations. This will insure that if the pushbutton is clicked while in a DCGET with a validation the validation code block will not be evaluated. The function DC_BitmapTransparentColor() may be used to set the default transparent color for pushbuttons that have bitmaps as captions.

Examples:

Run XDEMO.EXE - Sample Group 6 - MxPushButton

Files:

DCMXBUTT.CH

See Also:

   @ DCTOOLBAR
   @ DCMXPUSHBUTTON


DCPANEL

Anchor a Dialog Window to the perimiter of a main Dialog

DCPANEL is used to create Dialog windows around the perimiter of the a main dialog window that are automatically resized when the dialog is resized and are children of the main XbpDialog() object rather than the drawingArea. This allows for panels which can be used as parents for any other objects that are anchored to the main dialog window and cannot be hidden by other child windows.<br><br>A single dialog may have multiple panels. Each panel can be individually hidden from view which will shift all other panels to the top, bottom, etc. The panel is a window of the XbpDialog() type class and can be the parent of any other type of DC* object.<br><br>

Syntax:

DCPANEL <oDialog>                   ;
      [DRAWINGAREA <oDrawingArea>]  ;
      [ALIGN <nAlign>]              ;
      [HEIGHT <nHeight>]            ;
      [WIDTH <nWidth>]              ;
      [BITMAP <ncoBitMap>]          ;
      [BORDER <nBorder>]            ;
      [COLOR nbColorFG [,nbColorBG] ;
      [CARGO <xCargo>]              ;
      [PRESENTATION <aPres>]        ;
      [PREEVAL <bPreEval>]          ;
      [EVAL <bEval>]                ;
      [TITLE <cTitle>]              ;
      [HIDE <bHide>]                ;
      [ID <cId>]                    ;
      [GROUP <cGroup>]

Arguments:

<oDialog> is the name of the variable to assign as a storage
place for this object or the drawingArea of this object.  If
the DRAWINGAREA <oDrawingArea> clause is used, then <oDrawingArea>
will contain a pointer to XbpDialog():drawingArea and
<oDialog> will contain a point to XbpDialog().  If the
DRAWINGAREA clause is not used, then <oDialog> will contain a
pointer to XbpDialog():drawingArea and the only method for
obtaining a pointer to the XbpDialog() will be via
<oDialog>:setParent().

ALIGN <nAlign> is a numeric constant defined in DCDIALOG.CH.

DCGUI_ALIGN_TOP    - Attach statusbar to top of window
DCGUI_ALIGN_BOTTOM - Attach statusbar to bottom of window
DCGUI_ALIGN_RIGHT  - Attach statusbar to right side of window
DCGUI_ALIGN_LEFT   - Attach statusbar to left side of window

HEIGHT <nHeight> is the height (in pixels) of the status bar if
it has a top or bottom alignment.  This clause is ignored if the
status bar has a left or right alignment.

WIDTH <nWidth> is the width (in pixels) of the status bar if
it has a left or right alignment.  This clause is ignored if the
status bar has a top or bottom alignment.

BITMAP <ncoBitMap> is a bitmap to use as wallpaper for the panel.

BORDER <nBorder> is the border type of the panel.  Borders are
defined in XBP.CH. The default is XBPDLG_SIZEBORDER.  This allows
the panels to be resized by the user.

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the Statusbar object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Status Bar object is created.  The object is passed
to the code block.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the status bar will be hidden from view.  If
the value returned is .FALSE. then the status bar will be displayed.
The object is passed as a parameter to the code block.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETOBJECT() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

Files:

DCDIALOG.CH

See Also:

   DCSTATUSBAR


DCPRINT ABORT

Abort the print job

DCPRINT ABORT is used to abort a print job before it gets sent to the printer. This command must be called before the DCPRINT OFF command to insure that the print is properly aborted.<br><br>

Syntax:

DCPRINT ABORT ;
  [PRINTER <oPrinter>]

Arguments:

PRINTER <oPrinter> is the printer object returned by the
DCPRINT ON command or the DC_Printer() class.  If this clause
is not used then the printer object referenced by
DC_PrinterObject() is the default. .

Notes:

The :Eject() method looks at the current ::nPage instance variable and compares it to ::nFrom and ::nTo. If the current page is outside the range selected by the user then the page will not be ejected and only the ::nPage instance variable will be incremented.

Examples:

#include "dcprint.ch"
#include "inkey.ch"

PROCEDURE XTest( lPreview )

LOCAL aFor_Sale, oPrinter, i, nLineCount, cMemo, cMemoLine, cScrn

lPreview := IIF( Valtype(lPreview)='L',lPreview,.t.)

USE collect NEW

aFor_Sale := { 'No','Yes','Not Sure' }

BEGIN SEQUENCE

IF lPreview
  DCPRINT ON SIZE 60,100 TO oPrinter FONT '12.Courier' PREVIEW
ELSE
  DCPRINT ON SIZE 60,100 TO oPrinter FONT '12.Courier'
ENDIF

IF Valtype(oPrinter) # 'O' .OR. !oPrinter:lActive
  BREAK
ENDIF

DC_Gui(.t.)

IF !lPreview
  cScrn := DC_WaitOn()
ENDIF

DO WHILE !Eof() .AND. DC_PrinterOk() .AND. Inkey(.1) # K_ESC

  @ 2,0,20,45 DCPRINT BITMAP COLLECT->bitmap1
  @ 2,50,20,95 DCPRINT BITMAP COLLECT->bitmap2

  DCPRINT FONT '12.Courier'

  @ 23, 5, 37, 90 DCPRINT BOX

  @ 24,10 DCPRINT SAY '    Description:'
  @ 25,10 DCPRINT SAY '           Type:'
  @ 26,10 DCPRINT SAY '       Sub-Type:'
  @ 27,10 DCPRINT SAY '      Condition:'
  @ 28,10 DCPRINT SAY '       Location:'
  @ 29,10 DCPRINT SAY '      For Sale?:'
  @ 30,10 DCPRINT SAY '  Original Date:'
  @ 31,10 DCPRINT SAY '  Acquired Date:'
  @ 32,10 DCPRINT SAY ' Original Price:'
  @ 33,10 DCPRINT SAY 'Appraised Value:'
  @ 34,10 DCPRINT SAY '       Comments:'
  @ 35,10 DCPRINT SAY '      Bit Map 1:'
  @ 36,10 DCPRINT SAY '      Bit Map 2:'

  DCPRINT FONT '14.Terminal'

  @ 24,32 DCPRINT SAY COLLECT->descrip
  @ 25,32 DCPRINT SAY COLLECT->type
  @ 26,32 DCPRINT SAY COLLECT->sub_type
  @ 27,32 DCPRINT SAY COLLECT->condition
  @ 28,32 DCPRINT SAY COLLECT->location
  @ 29,32 DCPRINT SAY aFor_Sale[COLLECT->for_sale+1]
  @ 30,32 DCPRINT SAY COLLECT->date_orig
  @ 31,32 DCPRINT SAY COLLECT->date_acqu
  @ 32,32 DCPRINT SAY COLLECT->orig_price
  @ 33,32 DCPRINT SAY COLLECT->appr_value
  @ 34,32 DCPRINT SAY COLLECT->comments
  @ 35,32 DCPRINT SAY COLLECT->bitmap1
  @ 36,32 DCPRINT SAY COLLECT->bitmap2

  DCPRINT FONT '12.Arial'

  cMemo := Alltrim(COLLECT->memo)
  nLineCount := MLCount(cMemo)
  FOR i := 1 TO nLineCount - 1
    cMemoLine := MemoLine( cMemo, nil, i )
    IF Empty(cMemoLine)
      EXIT
    ENDIF
    @ 40+i,10 DCPRINT SAY cMemoLine
  NEXT

  DCPRINT EJECT

  SKIP

ENDDO

IF LastKey() = K_ESC
  DCPRINT ABORT
ENDIF

IF !lPreview
  DC_Impl(cScrn)
ENDIF

END SEQUENCE

DCPRINT OFF

RETURN

Files:

DCPRINT.CH

See Also:


DCPRINT ATTRIBUTE

Set the Attributes for printing with DCPRINT commands

DCPRINT ATTRIBUTE is used to set the attributes for use with the @..DCPRINT SAY, DCPRINT ?/??, @ DCPRINT BOX commands.

Syntax:

DCPRINT ATTRIBUTE ;
  [PRINTER <oPrinter>]  ;
  [TEXT | STRING <aString>] ;
  [LINE <aLine> ] ;
  [AREA <aArea> ] ;
  [MARKER <aMarker>] ;
  [WHEN <bWhen>]

Arguments:

<ocFont> is a character string containing the Compound Font
Name or a Font object.

PRINTER <oPrinter> is the printer object returned by the
DCPRINT ON command or the DC_Printer() class.  If this clause
is not used then the printer object referenced by
DC_PrinterObject() is the default.

TEXT | STRING <aString> is an attribute array that meets the
specification for string attributes used by @ DCPRINT SAY.  See
the Alaska documentation for GraSetAttrString() for more
information about the specification for this array.

LINE <aLine> is an attribute array that meets the
specification for line attributes used by @ DCPRINT BOX.  See
the Alaska documentation for GraSetAttrLine() for more
information about the specification for this array.

AREA <aArea> is an attribute array that meets the
specification for area attributes used by @ DCPRINT BOX.  See
the Alaska documentation for GraSetAttrArea() for more
information about the specification for this array.

MARKER <aMarker> is an attribute array that meets the
specification for line attributes used by @ DCPRINT MARKER.  See
the Alaska documentation for GraSetAttrMarker() for more
information about the specification for this array.

WHEN <bWhen> is a condition codeblock that is evaluated before
the command is executed during previewing and printing from
preview.  The DC_Printer() object is passed to the code block.
The code block must return a logical .TRUE. to enable the command.

Examples:

#include "dcprint.ch"

PROCEDURE XTest( lPreview )

LOCAL aFor_Sale, oPrinter, i, nLineCount, cMemo, cMemoLine, cScrn

lPreview := IIF( Valtype(lPreview)='L',lPreview,.t.)

USE collect NEW

aFor_Sale := { 'No','Yes','Not Sure' }

BEGIN SEQUENCE

IF lPreview
  DCPRINT ON SIZE 60,100 TO oPrinter FONT '12.Courier' PREVIEW
ELSE
  DCPRINT ON SIZE 60,100 TO oPrinter FONT '12.Courier'
ENDIF

IF Valtype(oPrinter) # 'O' .OR. !oPrinter:lActive
  BREAK
ENDIF

DC_Gui(.t.)

IF !lPreview
  cScrn := DC_WaitOn()
ENDIF

DO WHILE !Eof()

  @ 2,0,20,45 DCPRINT BITMAP COLLECT->bitmap1
  @ 2,50,20,95 DCPRINT BITMAP COLLECT->bitmap2

  DCPRINT FONT '12.Courier'

  @ 23, 5, 37, 90 DCPRINT BOX

  @ 24,10 DCPRINT SAY '    Description:'
  @ 25,10 DCPRINT SAY '           Type:'
  @ 26,10 DCPRINT SAY '       Sub-Type:'
  @ 27,10 DCPRINT SAY '      Condition:'
  @ 28,10 DCPRINT SAY '       Location:'
  @ 29,10 DCPRINT SAY '      For Sale?:'
  @ 30,10 DCPRINT SAY '  Original Date:'
  @ 31,10 DCPRINT SAY '  Acquired Date:'
  @ 32,10 DCPRINT SAY ' Original Price:'
  @ 33,10 DCPRINT SAY 'Appraised Value:'
  @ 34,10 DCPRINT SAY '       Comments:'
  @ 35,10 DCPRINT SAY '      Bit Map 1:'
  @ 36,10 DCPRINT SAY '      Bit Map 2:'

  DCPRINT FONT '14.Terminal'

  @ 24,32 DCPRINT SAY COLLECT->descrip
  @ 25,32 DCPRINT SAY COLLECT->type
  @ 26,32 DCPRINT SAY COLLECT->sub_type
  @ 27,32 DCPRINT SAY COLLECT->condition
  @ 28,32 DCPRINT SAY COLLECT->location
  @ 29,32 DCPRINT SAY aFor_Sale[COLLECT->for_sale+1]
  @ 30,32 DCPRINT SAY COLLECT->date_orig
  @ 31,32 DCPRINT SAY COLLECT->date_acqu
  @ 32,32 DCPRINT SAY COLLECT->orig_price
  @ 33,32 DCPRINT SAY COLLECT->appr_value
  @ 34,32 DCPRINT SAY COLLECT->comments
  @ 35,32 DCPRINT SAY COLLECT->bitmap1
  @ 36,32 DCPRINT SAY COLLECT->bitmap2

  DCPRINT FONT '12.Arial'

  cMemo := Alltrim(COLLECT->memo)
  nLineCount := MLCount(cMemo)
  FOR i := 1 TO nLineCount - 1
    cMemoLine := MemoLine( cMemo, nil, i )
    IF Empty(cMemoLine)
      EXIT
    ENDIF
    @ 40+i,10 DCPRINT SAY cMemoLine
  NEXT

  DCPRINT EJECT

  SKIP

ENDDO

IF !lPreview
  DC_Impl(cScrn)
ENDIF

END SEQUENCE

DCPRINT OFF

RETURN

Files:

DCPRINT.CH

See Also:


DCPRINT EJECT

Eject the printer page

DCPRINT EJECT has a dual purpose depending on whether the print output is going to a print device or to the PREVIEW window.<br><br> If the PREVIEW clause was used in the DCPRINT ON command, then DCPRINT EJECT will start a new page and display a preview window. The preview window includes "zoom", scrollbars, next and previous buttons. Each time DCPRINT EJECT is encountered in the code the next page is displayed and stored in a buffer. The NEXT button on the Preview window will exit the preview and return control to the print loop. The PREVIOUS button on the Preview window will display the previously buffered page.<br><br> If the NONSTOP sub-clause of the PREVIEW clause is used, then DCPRINT EJECT will only start a new page but will not stop and give control to the preview window until the DCPRINT OFF or DCPRINT GROUPEJECT command is encountered in the code.<br><br> If the PREVIEW clause was NOT USED in the DCPRINT ON command, the DCPRINT EJECT is used to eject the printer paper, start a new page and set the printer row/column to 0,0.

Syntax:

DCPRINT EJECT ;
  [PRINTER <oPrinter>]

Arguments:

PRINTER <oPrinter> is the printer object returned by the
DCPRINT ON command or the DC_Printer() class.  If this clause
is not used then the printer object referenced by
DC_PrinterObject() is the default. .

Notes:

The :Eject() method looks at the current ::nPage instance variable and compares it to ::nFrom and ::nTo. If the current page is outside the range selected by the user then the page will not be ejected and only the ::nPage instance variable will be incremented.

Examples:

#include "dcprint.ch"

PROCEDURE XTest( lPreview )

LOCAL aFor_Sale, oPrinter, i, nLineCount, cMemo, cMemoLine, cScrn

lPreview := IIF( Valtype(lPreview)='L',lPreview,.t.)

USE collect NEW

aFor_Sale := { 'No','Yes','Not Sure' }

BEGIN SEQUENCE

IF lPreview
  DCPRINT ON SIZE 60,100 TO oPrinter FONT '12.Courier' PREVIEW
ELSE
  DCPRINT ON SIZE 60,100 TO oPrinter FONT '12.Courier'
ENDIF

IF Valtype(oPrinter) # 'O' .OR. !oPrinter:lActive
  BREAK
ENDIF

DC_Gui(.t.)

IF !lPreview
  cScrn := DC_WaitOn()
ENDIF

DO WHILE !Eof()

  @ 2,0,20,45 DCPRINT BITMAP COLLECT->bitmap1
  @ 2,50,20,95 DCPRINT BITMAP COLLECT->bitmap2

  DCPRINT FONT '12.Courier'

  @ 23, 5, 37, 90 DCPRINT BOX

  @ 24,10 DCPRINT SAY '    Description:'
  @ 25,10 DCPRINT SAY '           Type:'
  @ 26,10 DCPRINT SAY '       Sub-Type:'
  @ 27,10 DCPRINT SAY '      Condition:'
  @ 28,10 DCPRINT SAY '       Location:'
  @ 29,10 DCPRINT SAY '      For Sale?:'
  @ 30,10 DCPRINT SAY '  Original Date:'
  @ 31,10 DCPRINT SAY '  Acquired Date:'
  @ 32,10 DCPRINT SAY ' Original Price:'
  @ 33,10 DCPRINT SAY 'Appraised Value:'
  @ 34,10 DCPRINT SAY '       Comments:'
  @ 35,10 DCPRINT SAY '      Bit Map 1:'
  @ 36,10 DCPRINT SAY '      Bit Map 2:'

  DCPRINT FONT '14.Terminal'

  @ 24,32 DCPRINT SAY COLLECT->descrip
  @ 25,32 DCPRINT SAY COLLECT->type
  @ 26,32 DCPRINT SAY COLLECT->sub_type
  @ 27,32 DCPRINT SAY COLLECT->condition
  @ 28,32 DCPRINT SAY COLLECT->location
  @ 29,32 DCPRINT SAY aFor_Sale[COLLECT->for_sale+1]
  @ 30,32 DCPRINT SAY COLLECT->date_orig
  @ 31,32 DCPRINT SAY COLLECT->date_acqu
  @ 32,32 DCPRINT SAY COLLECT->orig_price
  @ 33,32 DCPRINT SAY COLLECT->appr_value
  @ 34,32 DCPRINT SAY COLLECT->comments
  @ 35,32 DCPRINT SAY COLLECT->bitmap1
  @ 36,32 DCPRINT SAY COLLECT->bitmap2

  DCPRINT FONT '12.Arial'

  cMemo := Alltrim(COLLECT->memo)
  nLineCount := MLCount(cMemo)
  FOR i := 1 TO nLineCount - 1
    cMemoLine := MemoLine( cMemo, nil, i )
    IF Empty(cMemoLine)
      EXIT
    ENDIF
    @ 40+i,10 DCPRINT SAY cMemoLine
  NEXT

  DCPRINT EJECT

  SKIP

ENDDO

IF !lPreview
  DC_Impl(cScrn)
ENDIF

END SEQUENCE

DCPRINT OFF

RETURN

Files:

DCPRINT.CH

See Also:

   DCPRINT ON
   DCPRINT GROUPEJECT


DCPRINT ENDPAGE

Start a new Page in a Print Job

DCPRINT ENDPAGE ends the current page within the print job. <br><br>DCPRINT ENDPAGE ends the current page but no new page is begun. After DCPRINT ENDPAGE, the print job is temporarily halted between pages. This can be used by the application to change the following print attributes before the next page is begun via a call to DCPRINT STARTPAGE.<br><br>Print attributes that may be changed after DCPRINT ENDPAGE <br><br> Attribute Related command <br><br> Page Orientation DCPRINT ORIENTATION Paper Bin DCPRINT PAPERBIN Form Size DCPRINT SIZE <br><br>

Syntax:

DCPRINT ENDPAGE

Examples:

FUNCTION XTest()

nOrientation := 1

nRows := 60
nCols := 80
cFont := '12.Courier New'

DCPRINT ON
DCPRINT SIZE 60,80
DCPRINT FONT cFont

FOR nPage := 1 TO 4

  @ 2, 10 DCPRINT SAY 'This is Page ' + Alltrim(Str(nPage)) + ;
          IIF(nOrientation=1,' (PORTRAIT - Bin 1)',' (LANDSCAPE - Bin 2)' )

  FOR i := 5 to nRows - IIF( nOrientation=1,10,20)
    cString := ''
    FOR j := 10 TO IIF(nOrientation=1,70,120)
      cString += Alltrim(Str(j%10))
    NEXT
    @ i, 10 DCPRINT SAY cString
  NEXT

  DCPRINT ENDPAGE
  IF nPage % 2 == 0
    nOrientation := 1
    nPaperBin := 1
    nRows := 60
    nCols := 80
    cFont := '12.Courier New'
  ELSE
    nOrientation := 2
    nPaperBin := 2
    nRows := 60
    nCols := 130
    cFont := '9.Courier New'
  ENDIF
  DCPRINT ORIENTATION nOrientation
  DCPRINT PAPERBIN nPaperBin
  DCPRINT SIZE nRows, nCols
  DCPRINT FONT cFont
  DCPRINT STARTPAGE
NEXT

DCPRINT OFF

RETURN nil

Files:

DCPRINT.CH

See Also:

   DCPRINT STARTPAGE
   DCPRINT ON
   DCPRINT ORIENTATION
   DCPRINT PAPERBIN


DCPRINT EVAL

Evaluate a code block to imbed custom graphs in printed page

DCPRINT EVAL is used to run any special print routine and imbed the results within the printed page or preview window. This command is handy for printing routines such as pie-charts and graphs.<br><br>

Syntax:

DCPRINT EVAL <bEval> ;
  [PRINTER <oPrinter>] ;
  [WHEN <bWhen>]

Arguments:

<bEval> is the code block to evaluate.  The DC_Printer() object
is passed as a parameter to the code block.

PRINTER <oPrinter> is the printer object returned by the
DCPRINT ON command or the DC_Printer() class.  If this clause
is not used then the printer object referenced by
DC_PrinterObject() is the default.

WHEN <bWhen> is a condition codeblock that is evaluated before
the command is executed during previewing and printing from
preview.  The DC_Printer() object is passed to the code block.
The code block must return a logical .TRUE. to enable the command.

Examples:

FUNCTION XTest()

LOCAL oPrinter, i

DCPRINT ON TO oPrinter PREVIEW FONT '6.Terminal'

FOR i := 5 TO 20
  @ i,10 DCPRINT SAY 'This is line ' + Alltrim(Str(i))
NEXT

FOR i := 25 TO 40
  GraStringAt( oPrinter:oPS, oPrinter:PenCoords(i,10),  ;
               'This is line ' + Alltrim(Str(i)) )
NEXT

DCPRINT EJECT

@ 5,10 DCPRINT SAY 'Look at the below Pie Chart' ;
       FONT '14.Arial Bold'

DCPRINT EVAL {|o|DrawPieChart(o)}

DCPRINT OFF

RETURN nil

* -------------

FUNCTION DrawPieChart( oPrinter )

LOCAL nX, nY, nRadius,  nStartAngle, aAngle, ;
      aPattern, i, aPenCoords

aPenCoords := oPrinter:PenCoords(20,40)

nX       := aPenCoords[1]        // mid-point of the
nY       := aPenCoords[2]        // pie chart
nRadius  := 350                  // radius
aAngle   := { 30, 100, 15, 75, 80, 60 }
aPattern := { ;                  // various fill attributes
         GRA_SYM_DENSE2, ;
         GRA_SYM_DIAG1 , ;
         GRA_SYM_DENSE4, ;
         GRA_SYM_DIAG2 , ;
         GRA_SYM_DENSE6, ;
         GRA_SYM_DIAG3   }

nStartAngle := 45                // starting angle

FOR i := 1 TO LEN( aAngle )      // draw filled arcs
  DrawFilledPartialArc( {nX, nY}, nRadius, ;
                               nStartAngle, aAngle[i], ;
                               aPattern[i], .T., oPrinter:oPS )
  nStartAngle += aAngle[i]      // increment starting angle
NEXT

RETURN nil

*****************************************
* Draws filled arcs                     *

*****************************************
FUNCTION DrawFilledPartialArc( aCenter, ;
                               nRadius, ;
                               nStartAngle, ;
                               nSweepAngle, ;
                               nPattern , ;
                               lOutline, ;
                               oPS )
LOCAL aAttr, nSegment

aAttr := Array( GRA_AA_COUNT )   // select fill pattern
aAttr [ GRA_AA_SYMBOL ] := nPattern

aAttr := GraSetAttrArea( oPS, aAttr )

                                // open segment
nSegment := GraSegOpen( oPS, GRA_SEG_MODIFIABLE )
GraPathBegin( oPS )             // define path
GraPos( oPS, aCenter )          // define arc
GraArc( oPS, aCenter, nRadius,, nStartAngle, nSweepAngle )

GraPathEnd( oPS, .T. )          // end path definition
GraSegClose( oPS )              // close segment

GraSegDraw( oPS, nSegment )     // create path for drawing

GraPathFill( oPS )              // fill path

IF lOutline
  GraSegDraw( oPS, nSegment )   // recreate path
  GraPathOutline( oPS )         // outline path
ENDIF

GraSegDestroy( oPS, nSegment)   // delete segment
GraSetAttrArea( oPS, aAttr )    // reset old attributes

RETURN NIL

Files:

DCPRINT.CH

See Also:


DCPRINT FIXED

Set FIXED mode ON/OFF within a print job

DCPRINT FIXED ON will print each character in fixed columns (even when using proportional fonts). <br><br>DCPRINT FIXED OFF will cause characters will be printed in the same proportion as the chosen font.

Syntax:

DCPRINT FIXED ON / OFF

Files:

DCPRINT.CH

See Also:

   DCPRINT ON


DCPRINT FONT

Set the Font for printing with @..SAY style coordinates

DCPRINT FONT is used to set the font for use with the @..DCPRINT SAY or DCPRINT ?/?? commands.

Syntax:

DCPRINT FONT <ocFont> ;
  [CODEPAGE <nCodePage>] ;
  [PRINTER <oPrinter>] ;
  [WHEN <bWhen>]

Arguments:

<ocFont> is a character string containing the Compound Font
Name or a Font object.

NOTE: To print with UNDERSCORE, use the word "Underscore" in
      the FONT clause. ex: "12.Arial Bold Underscore".

CODEPAGE <nCodePage> is the desired code page to use with the
selected font other than the default code page.

PRINTER <oPrinter> is the printer object returned by the
DCPRINT ON command or the DC_Printer() class.  If this clause
is not used then the printer object referenced by
DC_PrinterObject() is the default.

WHEN <bWhen> is a condition codeblock that is evaluated before
the command is executed during previewing and printing from
preview.  The DC_Printer() object is passed to the code block.
The code block must return a logical .TRUE. to enable the command.

Examples:

#include "dcprint.ch"

PROCEDURE XTest( lPreview )

LOCAL aFor_Sale, oPrinter, i, nLineCount, cMemo, cMemoLine, cScrn

lPreview := IIF( Valtype(lPreview)='L',lPreview,.t.)

USE collect NEW

aFor_Sale := { 'No','Yes','Not Sure' }

BEGIN SEQUENCE

IF lPreview
  DCPRINT ON SIZE 60,100 TO oPrinter FONT '12.Courier' PREVIEW
ELSE
  DCPRINT ON SIZE 60,100 TO oPrinter FONT '12.Courier'
ENDIF

IF Valtype(oPrinter) # 'O' .OR. !oPrinter:lActive
  BREAK
ENDIF

DC_Gui(.t.)

IF !lPreview
  cScrn := DC_WaitOn()
ENDIF

DO WHILE !Eof()

  @ 2,0,20,45 DCPRINT BITMAP COLLECT->bitmap1
  @ 2,50,20,95 DCPRINT BITMAP COLLECT->bitmap2

  DCPRINT FONT '12.Courier'

  @ 23, 5, 37, 90 DCPRINT BOX

  @ 24,10 DCPRINT SAY '    Description:'
  @ 25,10 DCPRINT SAY '           Type:'
  @ 26,10 DCPRINT SAY '       Sub-Type:'
  @ 27,10 DCPRINT SAY '      Condition:'
  @ 28,10 DCPRINT SAY '       Location:'
  @ 29,10 DCPRINT SAY '      For Sale?:'
  @ 30,10 DCPRINT SAY '  Original Date:'
  @ 31,10 DCPRINT SAY '  Acquired Date:'
  @ 32,10 DCPRINT SAY ' Original Price:'
  @ 33,10 DCPRINT SAY 'Appraised Value:'
  @ 34,10 DCPRINT SAY '       Comments:'
  @ 35,10 DCPRINT SAY '      Bit Map 1:'
  @ 36,10 DCPRINT SAY '      Bit Map 2:'

  DCPRINT FONT '14.Terminal'

  @ 24,32 DCPRINT SAY COLLECT->descrip
  @ 25,32 DCPRINT SAY COLLECT->type
  @ 26,32 DCPRINT SAY COLLECT->sub_type
  @ 27,32 DCPRINT SAY COLLECT->condition
  @ 28,32 DCPRINT SAY COLLECT->location
  @ 29,32 DCPRINT SAY aFor_Sale[COLLECT->for_sale+1]
  @ 30,32 DCPRINT SAY COLLECT->date_orig
  @ 31,32 DCPRINT SAY COLLECT->date_acqu
  @ 32,32 DCPRINT SAY COLLECT->orig_price
  @ 33,32 DCPRINT SAY COLLECT->appr_value
  @ 34,32 DCPRINT SAY COLLECT->comments
  @ 35,32 DCPRINT SAY COLLECT->bitmap1
  @ 36,32 DCPRINT SAY COLLECT->bitmap2

  DCPRINT FONT '12.Arial'

  cMemo := Alltrim(COLLECT->memo)
  nLineCount := MLCount(cMemo)
  FOR i := 1 TO nLineCount - 1
    cMemoLine := MemoLine( cMemo, nil, i )
    IF Empty(cMemoLine)
      EXIT
    ENDIF
    @ 40+i,10 DCPRINT SAY cMemoLine
  NEXT

  DCPRINT EJECT

  SKIP

ENDDO

IF !lPreview
  DC_Impl(cScrn)
ENDIF

END SEQUENCE

DCPRINT OFF

RETURN

Files:

DCPRINT.CH

See Also:


DCPRINT FORMSIZE

Change the form size within a print job

DCPRINT FORMSIZE sets the print form size within a print job.<br><br>A #define constant from DCPRINT.CH must be used for <nBin> . Valid constants have the prefix XBPPRN_FORM_. Alternatively, a value obtained via the oPrinter:oDC:setFormSize() method can be used. <br><br>This command may be used only after a DCPRINT ENDPAGE and before a DCPRINT STARTPAGE.

Syntax:

DCPRINT FORMSIZE <nFormSize>

Files:

DCPRINT.CH

See Also:

   DCPRINT ENDPAGE


DCPRINT GROUPEJECT

Preview the next print group

DCPRINT GROUPEJECT is used to allow for previewing of print jobs in "groups" of pages. For example, this can be used to step through a set of invoices in which each invoice may have a different number of pages. Each previewed invoice will be a "group" of pages. <br><br>Clicking the "Next" group button will exit the preview window and return a value of DCPRINT_GROUP_NEXT. By testing for this value in the print loop the record pointer can be moved to the next invoice for printing. <br><br>The "Print" button will print only the pages that are part of the group and are visible in the preview window. Each time DCPRINT GROUPEJECT is encountered in the code, control is given to the preview window. If the user clicks on "Top", "Prev", "Next" or "Bottom", the preview buffer is cleared and a respective numeric value is returned to be used for selecting the next group to preview.<br><br><br><br><br><br>

Syntax:

DCPRINT GROUPEJECT ;
  [PRINTER <oPrinter>] ;
  [TO <nStatus>]

Arguments:

PRINTER <oPrinter> is the printer object returned by the
DCPRINT ON command or the DC_Printer() class.  If this clause
is not used then the printer object referenced by
DC_PrinterObject() is the default.

TO <nStatus> is the name of a variable to store a numeric return
value based on the key clicked by the user.  The manifest constants
in the below table are defined in "DCPRINT.CH".

<nStatus>             Description
------------------    -------------------------------------------
DCPRINT_GROUP_FIRST   Returned when "Top" button is clicked
DCPRINT_GROUP_PREV    Returned when "Prev" button is clicked.
DCPRINT_GROUP_NEXT    Returned when "Next" button is clicked.
DCPRINT_GROUP_LAST    Returned when "Bottom" button is clicked.
DCPRINT_GROUP_NONE    Returned when "Ok" or "Cancel" button is clicked.

Examples:

#include "dcprint.ch"

PROCEDURE XTest

DCPRINT ON PREVIEW NONSTOP HIDE GROUPBUTTONS

USE INVOICES

DO WHILE .t.

  PrintInvoice() // code to print multiple pages of invoice

  DCPRINT GROUPEJECT TO nStatus

  IF nStatus == DCPRINT_GROUP_FIRST
    INVOICE->(dbGoTop())
  ELSEIF nStatus == DCPRINT_GROUP_PREV
    INVOICE->(dbSkip(-1))
  ELSEIF nStatus == DCPRINT_GROUP_NEXT
    INVOICE->(dbSkip(1))
  ELSEIF nStatus == DCPRINT_GROUP_LAST
    INVOICE->(dbGoBottom())
  ELSEIF nStatus == DCPRINT_GROUP_NONE
    EXIT
  ENDIF

ENDDO

DCPRINT OFF

RETURN

Files:

DCPRINT.CH

See Also:

   DCPRINT ON
   dc_printergroupeject()


DCPRINT OFF

Destroy a printer object

DCPRINT OFF destroys a printer object that was previously created with DCPRINT ON or DC_PrinterOn().

Syntax:

DCPRINT OFF ;
  [PRINTER <oPrinter>]

Arguments:

PRINTER <oPrinter> is the printer object returned by the
DCPRINT ON command or the DC_Printer() class.  If this clause
is not used then the printer object referenced by
DC_PrinterObject() is the default.

Examples:

#include "dcprint.ch"

PROCEDURE XTest( lPreview )

LOCAL aFor_Sale, oPrinter, i, nLineCount, cMemo, cMemoLine, cScrn

lPreview := IIF( Valtype(lPreview)='L',lPreview,.t.)

USE collect NEW

aFor_Sale := { 'No','Yes','Not Sure' }

BEGIN SEQUENCE

IF lPreview
  DCPRINT ON SIZE 60,100 TO oPrinter FONT '12.Courier' PREVIEW
ELSE
  DCPRINT ON SIZE 60,100 TO oPrinter FONT '12.Courier'
ENDIF

IF Valtype(oPrinter) # 'O' .OR. !oPrinter:lActive
  BREAK
ENDIF

DC_Gui(.t.)

IF !lPreview
  cScrn := DC_WaitOn()
ENDIF

DO WHILE !Eof()

  @ 2,0,20,45 DCPRINT BITMAP COLLECT->bitmap1
  @ 2,50,20,95 DCPRINT BITMAP COLLECT->bitmap2

  DCPRINT FONT '12.Courier'

  @ 23, 5, 37, 90 DCPRINT BOX

  @ 24,10 DCPRINT SAY '    Description:'
  @ 25,10 DCPRINT SAY '           Type:'
  @ 26,10 DCPRINT SAY '       Sub-Type:'
  @ 27,10 DCPRINT SAY '      Condition:'
  @ 28,10 DCPRINT SAY '       Location:'
  @ 29,10 DCPRINT SAY '      For Sale?:'
  @ 30,10 DCPRINT SAY '  Original Date:'
  @ 31,10 DCPRINT SAY '  Acquired Date:'
  @ 32,10 DCPRINT SAY ' Original Price:'
  @ 33,10 DCPRINT SAY 'Appraised Value:'
  @ 34,10 DCPRINT SAY '       Comments:'
  @ 35,10 DCPRINT SAY '      Bit Map 1:'
  @ 36,10 DCPRINT SAY '      Bit Map 2:'

  DCPRINT FONT '14.Terminal'

  @ 24,32 DCPRINT SAY COLLECT->descrip
  @ 25,32 DCPRINT SAY COLLECT->type
  @ 26,32 DCPRINT SAY COLLECT->sub_type
  @ 27,32 DCPRINT SAY COLLECT->condition
  @ 28,32 DCPRINT SAY COLLECT->location
  @ 29,32 DCPRINT SAY aFor_Sale[COLLECT->for_sale+1]
  @ 30,32 DCPRINT SAY COLLECT->date_orig
  @ 31,32 DCPRINT SAY COLLECT->date_acqu
  @ 32,32 DCPRINT SAY COLLECT->orig_price
  @ 33,32 DCPRINT SAY COLLECT->appr_value
  @ 34,32 DCPRINT SAY COLLECT->comments
  @ 35,32 DCPRINT SAY COLLECT->bitmap1
  @ 36,32 DCPRINT SAY COLLECT->bitmap2

  DCPRINT FONT '12.Arial'

  cMemo := Alltrim(COLLECT->memo)
  nLineCount := MLCount(cMemo)
  FOR i := 1 TO nLineCount - 1
    cMemoLine := MemoLine( cMemo, nil, i )
    IF Empty(cMemoLine)
      EXIT
    ENDIF
    @ 40+i,10 DCPRINT SAY cMemoLine
  NEXT

  DCPRINT EJECT

  SKIP

ENDDO

IF !lPreview
  DC_Impl(cScrn)
ENDIF

END SEQUENCE

DCPRINT OFF

RETURN

Files:

DCPRINT.CH

See Also:

   dc_printeroff()
   DCPRINT ON


DCPRINT ON

Create a printer class object for @..SAY style printing

DCPRINT ON creates a printer class which is used to create reports that use row/column addressing identical to the @..SAY addressing used by Clipper. This class provides for an easy migration of existing reports so that they may use the more powerful features of the Windows print manager like font selection and selection of a network printer.

Syntax:

DCPRINT ON ;
   [TO <oPrinter>] ;
   [OPTIONS <aDefaultOptions>] ;
   [NAME <cPrinterName>] ;
   [SIZE <nRows>,<nCols>] ;
   [PAGES <nFrom>,<nTo>] ;
   [VIEWPORT <nX1>,<nY1>,<nX2>,<nY2>] ;
   [ALLPAGES] ;
   [COPIES <nCopies>] ;
   [COPYLOOP] ;
   [COLLATE] ;
   [TEXTONLY] ;
   [TOFILE] ;
   [OUTFILE <cOutFile> [OVERWRITE] [APPEND]] ;
   [FONT <ocFont>] ;
   [FIXED] ;
   [NOSCALE] [PIXEL] ;
   [PAGESIZE <nPageWidth>,<nPageHeight>] ;
   [UNITS <nUnits>] ;
   [USEDEFAULT ] ;
   [FORCEPRINTDIALOG] ;
   [HANDLER <bHandler>] ;
   [FONTBUTTON] ;
   [ORIENTATION <nOrientation>] ;
   [PAPERBIN <nPaperBin>] ;
   [FORMSIZE <nFormSize>] ;
   [DUPLEXMODE <nDuplexMode>] ;
   [COLORMODE <nColorMode>] ;
   [RESOLUTION <nResolution>] ;
   [MARGIN <anMargin>] ;
   [TITLE <cTitle>] ;
   [CANCELENABLE] ;
   [AUTOEJECT] ;
   [DIALOGSTYLE <nDialogStyle>] ;
   [GRID] ;
   [PREVIEW] ;
     [ZOOMFACTOR <nZoomFactor> [,<nZoomIncr>]] ;
     [SCROLLFACTOR <nScrollFactor>] ;
     [PPOSITION <nStartCol>,<nStartRow>] ;
     [PSIZE <nWidth>,<nHeight>] ;
     [NOSTOP] ;
     [HIDE] ;
     [NOPRINTBUTTON] ;
     [BUSYMESSAGE <cBusyMsg>] ;
     [FINDBUTTON] ;
     [BUTTONS <aButtons>] ;
     [ADDBUTTONS <aAddButtons>] ;
     [GROUPBUTTONS] ;
     [EXITAFTERPRINT] ;
     [NOSCROLLBARS] ;
   [ACROBAT [NOSPAWN]] ;
   [IMAGEWRITER] ;
   [XPSWRITER [NOSPAWN]] ;
   [EXCEL]

Arguments:

TO <oPrinter> is a variable to store the printer object.

OPTIONS <aDefaultOptions> is used to establish the default
options for print jobs.  <aDefaultOptions> is an array that was
previously created by the DCPRINT OPTIONS command.

NAME <cPrinterName> is the name of the printer.  If
this argument is not used, a printer dialog will appear
for the operator to choose a printer and other options.

SIZE <nRows>, <nCols> is the number of print rows and columns.
The default is 66 rows, 80 columns for compatibility with existing
Xbase language reports.  This establishes a "grid" on the page
so the page may be addressed using text-based coordinates.  To
get tighter control of the pen location on the paper use very
high numbers, such as 660,800.  When using commands such as
@ <nRow>, <nCol> DCPRINT SAY, the <nRow> and <nCol> coordinates
are the grid coordinates.

PAGES <nFrom>, <nTo> is the starting and ending page.
The default is All pages.

VIEWPORT <nX1>, <nY1>, <nX2>, <nY2> contains the coordinates for
the lower left and upper right corners of the viewport. Including
this parameter is optional and sets the size of the viewport.

The viewport is important for graphic output in the device context
linked to the printer or preview presentation space. The viewport
coordinates are relative to the point {0,0} of the output device
or device context. In the viewport itself everything is displayed
that is visible in the page of the presentation space. The
viewport contents are transferred to the output device (the device
context).

Note: When dimensioning the viewport two automatic graphic
transformations are performed. One is the transformation of the
page to the viewport and the other is the transformation of the
viewport to the output device (the device context). See the
Xbase++ documentation for more information about the ViewPort.

ALLPAGES will disable the users selection of pages to print
in the printer dialog window.

COPIES <nCopies> is the number of copies to print.  The
default is 1.

COLLATE will collate the pages.

COPYLOOP is used to disable the sending of the request to the
print driver to print multiple copies.  If the user selects
copies from the print dialog screen the value selected will be
placed in the oPrinter:nCopies variable and the programmer must
used this value in a FOR..NEXT loop to print multiple copies.

FONT <ocFont> is the starting font.  May be a character string
with a Font name or a font object.  Default is 12.Courier.

FIXED will print each character in fixed columns (even when
using proportional fonts).  If argument is not used,
characters will be printed in the same proportion as the
chosen font.

NOSCALE or PIXEL will cause coordinates NOT to be text-based.
Normally, coordinates are text-based and are scaled to the
coordinate system defined by the UNITS command.  The scaling is
based on the SIZE clause.

PAGESIZE <nPageWidth>, <nPageHeight> determines the page size of
the presentation space. The page size depends on the unit <nUnits>
of the coordinate system. The origin of the coordinate system (the
point {0,0}) is the lower left corner of the page.

UNITS <nUnits> optionally sets the unit for the coordinate system
of the presentation space. The default unit is pixel. To define a
different unit, a #define constant must be passed for <nUnits> .
The following table lists the valid constants for <nUnits> .

 Constant          Description

 GRA_PU_ARBITRARY  Any unit. The coordinate system is scaled to
                   the viewport.
 GRA_PU_PIXEL      Unit is a pixel
 GRA_PU_LOMETRIC * Unit is 0.1 millimeter
 GRA_PU_HIMETRIC   Unit is 0.01 millimeter
 GRA_PU_LOENGLISH  Unit is 0.1 inch
 GRA_PU_HIENGLISH  Unit is 0.01 inch
 GRA_PU_TWIPS      Unit is 1/1440 inch

*) Default value

TEXTONLY will output the report in text-only mode.  The user will
be prompted for the name of a text file to create unless the
OUTFILE <cOutFile> clause is used.  Only text commands will be
processed in TEXTONLY mode.  OVERWRITE will automatically
overwrite any existing file.  APPEND will automatically append
the output to the existing file.

TOFILE is used to send the print job to a file rather than
directly to the print spooler. The user will be prompted for
the name of a print image file to create unless the OUTFILE
<cOutFile> clause is used.  The file that is created may be
later sent to the print spooler via RunShell() as per the
following example:

 DCPRINT ON TOFILE OUTFILE JUNK.PRN
 ..... print commands
 RunShell( '/C COPY JUNK.PRN \\gigadrive\sc254887_p1' )

USEDEFAULT will send the print job to the currently selected
Windows default printer driver without displaying a Printer
dialog window (unless FORCEPRINTDIALOG) is used.

FORCEPRINTDIALOG will force the Printer dialog window to be
displayed.

HANDLER <bHandler> is a codeblock to evaluate in the event loop
of the preview window.  This gives the programmer control over
previewing operations.  The DC_Printer() object is passed as a
parameter when evaluating the code block.  A numeric value is
returned from the code block:

  VALUE             FUNCTION
 ------------------ -----------------------------------------
 DCGUI_NONE         Normal operation
 DCGUI_IGNORE       Ignore this event (do not handle it)
 DCGUI_EXIT_OK      Exit the event loop and return control
                    to printing loop.
 DCGUI_EXIT_ABORT   Exit the event loop and set the ::terminated
                    flag of the DC_Printer() object to abort
                    the print routine.

FONTBUTTON will enable the FONT button on the Printer dialog
for the operator to select a font for the print operation.
Note: Any FONT clause in DCPRINT commands will override the
selection by the operator.

ORIENTATION <nOrientation> is used to select the paper orientation
the output is to the printer.

  <nOrientation>    Mode
  --------------    ----------------------------
        1           Portrait (default)
        2           Landscape

PAPERBIN <nPaperBin> is used to instruct the printer which paper
bin to use for the print job.  A #define constant from XBPDEV.CH
must be used for <nPaperBin> . Valid constants have the prefix
XBPPRN_PAPERBIN_.

FORMSIZE <nFormSize> is used to instruct the printer what paper
format is being used. Common formats are Letter, Legal or A4.
They are selected by their numeric ID which is available as a
#define constant from XBPDEV.CH.  Valid constants have the prefix
XBPPRN_FORMSIZE_.

DUPLEXMODE <nDuplexMode> is used to set the duplex mode for
double-sided printing.  The mode is selected by a numeric ID
which is available as a #define constant from XBPDEV.CH.  Valid
constants have the prefix XBPPRN_DUPLEXMODE_.

COLORMODE <nColorMode> is used to set the color mode for printing.
The mode is selected by a numeric ID which is available as a
#define constant from XBPDEV.CH.  Valid constants have the prefix
XBPPRN_COLORMODE_.

RESOLUTION <nResolution> is used to set the resolution for printing.
The mode is selected by a numeric ID which is available as a
#define constant from XBPDEV.CH.  Valid constants have the prefix
XBPPRN_RESOLUTION_.

MARGIN <anMargin> may be a numeric value or an array of two
numeric values.  If it is a numeric value, then this will be the
value of the left margin.  If it is an array, then the first
element is the TOP margin and the second element is the LEFT
margin.  The margins may be negative and/or decimal values.

TITLE <cTitle> is the title to display in the title bar area of the
Preview window and the Printer Dialog window.   This is also the
name of the print job that is sent to the spooler.

CANCELENABLE will display a dialog window during printing that
includes a CANCEL button to cancel the print job.  It is required
that the function DC_PrinterOK() be included in your print loop
to cancel the print loop because cancelling will cause
DC_PrinterOK() to return a .FALSE.

AUTOEJECT will cause an automatic page eject whenever an
attempt is made to print past the last print row defined by the
SIZE <nRows>, <nCols> command or whenever an attempt is made to
print to a row that is higher on the page than the last printed
row.  This feature is provided for compatability with existing
Clipper reports.

DIALOGSTYLE <nDialogStyle> allows users of eXPress++ 1.3 and earlier
versions to display the same style dialog in their 1.5 applications
as was displayed in 1.3.  Xbase++ 1.5 introduced a new
XbpPrinterDialog() class which was incorporated in eXPress++ 1.5.
This new dialog is created by the print driver whereas the old
dialog was created by eXPress++ and also included a FONT button for
selecting a print font.  DIALOGSTYLE DCPRINT_DIALOG_EXPRESS will
display the 1.3 style printer dialog.

GRID will print a cross-hatch grid on the paper or preview
window at each text-based row and column defined by the SIZE
clause.  The grid will also include row/column numbers at the
top and left border.  The GRID option will aid in the designing
of reports.

PREVIEW will cause the printed output to be sent to the
display rather than the print device.  The PREVIEW arguments
causes the methods of the DC_PRINTER() class to write to an
XbpDialog() GUI dialog screen rather than to an XbpPrinter()
object.

ZOOMFACTOR <nZoomFactor> is a numeric value to use as the
base for the initial zoom value of the Preview window.  This
clause is used only in PREVIEW mode. The default is 1.0.  A
higher number will cause the text and graphics in the screen
to be larger.  The minimum value is .25.  Numeric values from
0.25 to 4.00 are recommended.  <nZoomIncr> is a numeric value
specifying the zoom resolution.  A smaller number will cause
each click of the ZOOM+/ZOOM- key to have a smaller change.
The default value is .25.

SCROLLFACTOR <nScrollFactor> is used to set the sensitivity of
the scroll bars in the PREVIEW window.  The default is 40.

PPOSITION <nStartCol>, <nStartRow> are the starting coordinates
of the PREVIEW window (in pixels) relative to the left, bottom
of the screen.  The default is 0,0.

PSIZE <nWidth>, <nHeight> is the width and height of the
PREVIEW window (in pixels).  If no size is given then the
window will be automatically sized to fit the screen.

NOSTOP will supress the automatic stop of program execution each
time a DCPRINT EJECT command or oPrinter:eject() method is
encountered in the program.  The control will then be given to
the event loop of the PREVIEW window.  If the NOSTOP clause is
used then the control will only be given to the PREVIEW window
when the command DCPRINT OFF or the function DC_PrinterOff() are
encountered in the program.

HIDE will hide the previewer window until the command DCPRINT OFF
or the function DC_PrinterOff() are encountered in the program.
If the HIDE clause is not used, each page will be visible in
the preview window as they are being created.

NOPRINTBUTTON will remove the 'Print' button from the preview
window, thereby disabling the ability to print while previewing.

BUSYMESSAGE <cBusyMsg> is a message to display while each
screen is being created.  Use this clause if your application
takes a long time to create a screen.

FINDBUTTON will paint a 'Find' button on the preview window.
Activating this button will popup a dialog window for the user to
enter "Text to find in Report".  The preview buffer will be
searched for a match and will jump to the page containing the
found text.  The found text will be outlined.

BUTTONS <aButtons> is an array that is used to configure the thirteen
(13) pushbuttons at the top of the preview window.  This allows the
buttons to be resized or deleted or the captions to be changed to
character string, numeric resource or bitmap.  Each sub-array is an
array of 3 elements:

 Element  Description
 -------  -----------------------------------------------
   1      Button Width (numeric). NIL for no change.
   2      Button Height (numeric). NIL for no change.
   3      Button Caption (numeric resource, string or
          XbpBitMap() object).  NIL for no change.
          This may also be an array of 2 bitmaps, to be
          used for the enabled and disabled condition
          of the button respectively.

The button(s) to be configured are defined by the DCPRINT_BUTTON*
constants in DCPRINT.CH.

 Constant                   Description
 -------------------------- -----------------------------------
 DCPRINT_BUTTON_PLUS        Plus (Zoom Out) Button
 DCPRINT_BUTTON_MINUS       Minus (Zoom In) Button
 DCPRINT_BUTTON_FIRSTPAGE   First Page Button
 DCPRINT_BUTTON_PREVPAGE    Previous Page Button
 DCPRINT_BUTTON_NEXTPAGE    Next Page Button
 DCPRINT_BUTTON_LASTPAGE    Last Page Button
 DCPRINT_BUTTON_PRINT       Print Button
 DCPRINT_BUTTON_FIND        Find Button
 DCPRINT_BUTTON_EXIT        Ok/Exit Button
 DCPRINT_BUTTON_FIRSTGROUP  First Group Button
 DCPRINT_BUTTON_PREVGROUP   Previous Group Button
 DCPRINT_BUTTON_NEXTGROUP   Next Group Button
 DCPRINT_BUTTON_LASTGROUP   Last Group Button

Example:

  In this example, the Find button is resized to a width of 50
  pixels and the caption is changed to BITMAP_FIND_1 (defined in
  DCBITMAP.CH).

  aButtons := Array(13)
  aButtons[DCPRINT_BUTTON_FIND] := { 50,nil,BITMAP_FIND_1 }

GROUPBUTTONS will paint four (4) "Group" buttons at the top of
the window.  These buttons are used in conjunction with the
DCPRINT GROUPEJECT command to allow control within the print loop
to manage the previewing of print projects in "groups".  For
example, this can be used to step through a set of invoices in
which each invoice may have a different number of pages.  Each
invoice will be a "group" of pages.  Click the "Next" group button
will exit the preview window and return a value of DCPRINT_GROUP_NEXT.
By testing for this value in the print loop the record pointer can
be moved to the next invoice for printing.

ADDBUTTONS <aAddButtons> is an array of pushbutton data.  Each sub-array
with add a pushbutton to the top toolbar of the preview window.
Each sub-array must consist of 4 elements:

  Element  Type  Description
  -------  ----  ---------------------------------------------
    [1]      N   Button width in pixels (default is 70)
    [2]      N   Button height in pixels (default is 20)
    [3]     C/O  Caption of button.  May be a character string
                 or an XbpBitmap object.
    [4]      B   Action code block

EXITAFTERPRINT will close the preview window after the print from
preview is selected.

NOSCROLLBARS will supress the creation of scrollbars in the preview window.

ACROBAT is used to invoke Acrobat Reader as the the print
previewer for a much more WYSIWIG preview of the print job.
DO NOT this clause with the PREVIEW, IMAGEWRITER, or DOCWRITER
clauses. To use this clause both the Acrobat Reader
(http://www.adobe.com) and the Win2PDF driver (http://daneprarie.com)
or BullZip drvier (http://bullzip.com) must be installed. The
Acrobat Reader is free and the Win2PDF driver is $39.00.  The
demo version of Win2PDF and BullZip are included.  The Win2PDF
driver works only on Windows NT, 2000, XP or Vista.  The BullZip
driver is free, however it requires that GhostScript be installed
on the workstation computer.  GhostScript can be downloaded at
http://www.bullzip.com/download/gsl/gslite.exe.  If the NOSPAWN
clause is used, the Acrobat reader with not be spawned to view the
print job.

IMAGEWRITER is used to invoke the 'Microsoft Office Document Image Writer'
as the the print previewer for a much more WYSIWIG preview of the
print job.  DO NOT this clause with the PREVIEW or ACROBAT clauses.
To use this clause the Microsoft Office Document Image Writer
must be installed on the workstation.  This is a printer driver
that is installed when Microsoft Office is installed.

XPSWRITER is used to invoke the 'Microsoft XPS Document Writer'
as the the print previewer for a much more WYSIWIG preview of the
print job.  DO NOT this clause with the PREVIEW or ACROBAT clauses.
To use this clause the Microsoft XPS Document Writer must be
installed on the workstation.  NOSPAWN will supress the launching
of the XPS Viewer.

EXCEL is used to create an Excel .XLS spreadsheet as the output.
CAUTION: Some print jobs to not translate well to Excel because
they are not columnar and/or do not contain much numeric data.
To get the best possible export, it is recommend that print code
be formatted using a technique that is compatible.  Look at the
\exp19\samples\printer\excel.prg file for an example.

Examples:

#include "dcprint.ch"

PROCEDURE XTest( lPreview )

LOCAL aFor_Sale, oPrinter, i, nLineCount, cMemo, cMemoLine, cScrn

lPreview := IIF( Valtype(lPreview)='L',lPreview,.t.)

USE collect NEW

aFor_Sale := { 'No','Yes','Not Sure' }

BEGIN SEQUENCE

IF lPreview
  DCPRINT ON SIZE 60,100 TO oPrinter FONT '12.Courier' ;
  PREVIEW HIDE
ELSE
  DCPRINT ON SIZE 60,100 TO oPrinter FONT '12.Courier'
ENDIF

IF Valtype(oPrinter) # 'O' .OR. !oPrinter:lActive
  BREAK
ENDIF

DC_Gui(.t.)

IF !lPreview
  cScrn := DC_WaitOn()
ENDIF

DO WHILE !Eof()

  @ 2,0,20,45 DCPRINT BITMAP COLLECT->bitmap1
  @ 2,50,20,95 DCPRINT BITMAP COLLECT->bitmap2

  DCPRINT FONT '12.Courier'

  @ 23, 5, 37, 90 DCPRINT BOX

  @ 24,10 DCPRINT SAY '    Description:'
  @ 25,10 DCPRINT SAY '           Type:'
  @ 26,10 DCPRINT SAY '       Sub-Type:'
  @ 27,10 DCPRINT SAY '      Condition:'
  @ 28,10 DCPRINT SAY '       Location:'
  @ 29,10 DCPRINT SAY '      For Sale?:'
  @ 30,10 DCPRINT SAY '  Original Date:'
  @ 31,10 DCPRINT SAY '  Acquired Date:'
  @ 32,10 DCPRINT SAY ' Original Price:'
  @ 33,10 DCPRINT SAY 'Appraised Value:'
  @ 34,10 DCPRINT SAY '       Comments:'
  @ 35,10 DCPRINT SAY '      Bit Map 1:'
  @ 36,10 DCPRINT SAY '      Bit Map 2:'

  DCPRINT FONT '14.Terminal'

  @ 24,32 DCPRINT SAY COLLECT->descrip
  @ 25,32 DCPRINT SAY COLLECT->type
  @ 26,32 DCPRINT SAY COLLECT->sub_type
  @ 27,32 DCPRINT SAY COLLECT->condition
  @ 28,32 DCPRINT SAY COLLECT->location
  @ 29,32 DCPRINT SAY aFor_Sale[COLLECT->for_sale+1]
  @ 30,32 DCPRINT SAY COLLECT->date_orig
  @ 31,32 DCPRINT SAY COLLECT->date_acqu
  @ 32,32 DCPRINT SAY COLLECT->orig_price
  @ 33,32 DCPRINT SAY COLLECT->appr_value
  @ 34,32 DCPRINT SAY COLLECT->comments
  @ 35,32 DCPRINT SAY COLLECT->bitmap1
  @ 36,32 DCPRINT SAY COLLECT->bitmap2

  DCPRINT FONT '12.Arial'

  cMemo := Alltrim(COLLECT->memo)
  nLineCount := MLCount(cMemo)
  FOR i := 1 TO nLineCount - 1
    cMemoLine := MemoLine( cMemo, nil, i )
    IF Empty(cMemoLine)
      EXIT
    ENDIF
    @ 40+i,10 DCPRINT SAY cMemoLine
  NEXT

  DCPRINT EJECT

  SKIP

ENDDO

IF !lPreview
  DC_Impl(cScrn)
ENDIF

END SEQUENCE

DCPRINT OFF

RETURN

Files:

DCPRINT.CH

See Also:

   dc_printeron()
   DCPRINT OFF
   DCPRINT OPTIONS


DCPRINT OPTIONS

Create an option array for setting printing defaults

DCPRINT OPTIONS will create an option array to be used later with the DCPRINT ON command or DC_PrintFile() function.

Syntax:

DCPRINT OPTIONS ;
   [TO <aOptions>] ;
   [NAME <cPrinterName>] ;
   [SIZE <nRows>,<nCols>] ;
   [PAGES <nFrom>,<nTo>] ;
   [VIEWPORT <nX1>,<nY1>,<nX2>,<nY2>] ;
   [ALLPAGES] ;
   [COPIES <nCopies>] ;
   [COPYLOOP] ;
   [COLLATE] ;
   [TOFILE] ;
   [TEXTONLY [OUTFILE <cOutFile> [OVERWRITE] [APPEND]] ;
   [FONT <ocFont>] ;
   [FIXED] ;
   [NOSCALE] [PIXEL] ;
   [PAGESIZE <aPageSize>] ;
   [UNITS <nUnits>] ;
   [USEDEFAULT ] ;
   [FORCEPRINTDIALOG] ;
   [HANDLER <bHandler>] ;
   [FONTBUTTON] ;
   [ORIENTATION <nOrientation>] ;
   [PAPERBIN <nPaperBin>] ;
   [FORMSIZE <nFormSize>] ;
   [DUPLEXMODE <nDuplexMode>] ;
   [COLORMODE <nColorMode>] ;
   [RESOLUTION <nResolution>] ;
   [MARGIN <anMargin>] ;
   [TITLE <cTitle>] ;
   [CANCELENABLE] ;
   [AUTOEJECT] ;
   [DIALOGSTYLE <nDialogStyle>] ;
   [GRID] ;
   [PREVIEW] ;
     [ZOOMFACTOR <nZoomFactor> [,<nZoomIncr>]] ;
     [SCROLLFACTOR <nScrollFactor>] ;
     [PPOSITION <nStartCol>,<nStartRow>] ;
     [PSIZE <nWidth>,<nHeight>] ;
     [NOSTOP] ;
     [HIDE] ;
     [NOPRINTBUTTON] ;
     [BUSYMESSAGE <cBusyMsg>]

Arguments:

TO <aOptions> is the array to store the print options.

NAME <cPrinterName> is the name of the printer.  If
this argument is not used, a printer dialog will appear
for the operator to choose a printer and other options.

SIZE <nRows>, <nCols> is the number of print rows and columns.
The default is 66 rows, 80 columns for compatibility with existing
Xbase language reports.  This establishes a "grid" on the page
so the page may be addressed using text-based coordinates.  To
get tighter control of the pen location on the paper use very
high numbers, such as 660,800.  When using commands such as
@ <nRow>, <nCol> DCPRINT SAY, the <nRow> and <nCol> coordinates
are the grid coordinates.

PAGES <nFrom>, <nTo> is the starting and ending page.
The default is All pages.

VIEWPORT <nX1>, <nY1>, <nX2>, <nY2> contains the coordinates for
the lower left and upper right corners of the viewport. Including
this parameter is optional and sets the size of the viewport.

The viewport is important for graphic output in the device context
linked to the printer or preview presentation space. The viewport
coordinates are relative to the point {0,0} of the output device
or device context. In the viewport itself everything is displayed
that is visible in the page of the presentation space. The
viewport contents are transferred to the output device (the device
context).

Note: When dimensioning the viewport two automatic graphic
transformations are performed. One is the transformation of the
page to the viewport and the other is the transformation of the
viewport to the output device (the device context). See the
Xbase++ documentation for more information about the ViewPort.

ALLPAGES will disable the users selection of pages to print
in the printer dialog window.

COPIES <nCopies> is the number of copies to print.  The
default is 1.

COLLATE will collate the pages.

COPYLOOP is used to disable the sending of the request to the
print driver to print multiple copies.  If the user selects
copies from the print dialog screen the value selected will be
placed in the oPrinter:nCopies variable and the programmer must
used this value in a FOR..NEXT loop to print multiple copies.

TOFILE is used to send the print job to a file rather than
directly to the print spooler. The user will be prompted for
the name of a print image file to create unless the OUTFILE
<cOutFile> clause is used.  The file that is created may be
later sent to the print spooler via RunShell() as per the
following example:

 DCPRINT ON TOFILE JUNK.PRN
 ..... print commands
 RunShell( '/C COPY JUNK.PRN \\gigadrive\sc254887_p1' )

FONT <ocFont> is the starting font.  May be a character string
with a Font name or a font object.  Default is 12.Courier.

FIXED will print each character in fixed columns (even when
using proportional fonts).  If argument is not used,
characters will be printed in the same proportion as the
chosen font.

NOSCALE or PIXEL will cause coordinates NOT to be text-based.
Normally, coordinates are text-based and are scaled to the
coordinate system defined by the UNITS command.  The scaling is
based on the SIZE clause.

PAGESIZE <aPageSize) determines the page size of the presentation
space. <aPageSize> is an array of two elements that specifies the
dimensions of the page in the x and y direction (X = width,
Y = height). The page size depends on the unit <nUnits> of the
coordinate system. The origin of the coordinate system( the point
{0,0}) is the lower left corner of the page.

UNITS <nUnits> optionally sets the unit for the coordinate system
of the presentation space. The default unit is pixel. To define a
different unit, a #define constant must be passed for <nUnits> .
The following table lists the valid constants for <nUnits> .

 Constant          Description

 GRA_PU_ARBITRARY  Any unit. The coordinate system is scaled to
                   the viewport.
 GRA_PU_PIXEL      Unit is a pixel
 GRA_PU_LOMETRIC * Unit is 0.1 millimeter
 GRA_PU_HIMETRIC   Unit is 0.01 millimeter
 GRA_PU_LOENGLISH  Unit is 0.1 inch
 GRA_PU_HIENGLISH  Unit is 0.01 inch
 GRA_PU_TWIPS      Unit is 1/1440 inch

*) Default value

TEXTONLY will output the report in text-only mode.  The user will
be prompted for the name of a text file to create unless the
OUTFILE <cOutFile> clause is used.  Only text commands will be
processed in TEXTONLY mode.  OVERWRITE will automatically
overwrite any existing file.  APPEND will automatically append
the output to the existing file.

USEDEFAULT will send the print job to the currently selected
Windows default printer driver without displaying a Printer
dialog window (unless FORCEPRINTDIALOG) is used.

FORCEPRINTDIALOG will force the Printer dialog window to be
displayed.

HANDLER <bHandler> is a codeblock to evaluate in the event loop
of the preview window.  This gives the programmer control over
previewing operations.  The DC_Printer() object is passed as a
parameter when evaluating the code block.  A numeric value is
returned from the code block:

  VALUE             FUNCTION
 ------------------ -----------------------------------------
 DCGUI_NONE         Normal operation
 DCGUI_IGNORE       Ignore this event (do not handle it)
 DCGUI_EXIT_OK      Exit the event loop and return control
                    to printing loop.
 DCGUI_EXIT_ABORT   Exit the event loop and set the ::terminated
                    flag of the DC_Printer() object to abort
                    the print routine.

FONTBUTTON will enable the FONT button on the Printer dialog
for the operator to select a font for the print operation.
Note: Any FONT clause in DCPRINT commands will override the
selection by the operator.

ORIENTATION <nOrientation> is used to select the paper orientation
the output is to the printer.

  <nOrientation>    Mode
  --------------    ----------------------------
        1           Portrait (default)
        2           Landscape

PAPERBIN <nPaperBin> is used to instruct the printer which paper
bin to use for the print job.  A #define constant from XBPDEV.CH
must be used for <nPaperBin> . Valid constants have the prefix
XBPPRN_PAPERBIN_.

FORMSIZE <nFormSize> is used to instruct the printer what paper
format is being used. Common formats are Letter, Legal or A4.
They are selected by their numeric ID which is available as a
#define constant from XBPDEV.CH.  Valid constants have the prefix
XBPPRN_FORMSIZE_.

DUPLEXMODE <nDuplexMode> is used to set the duplex mode for
double-sided printing.  The mode is selected by a numeric ID
which is available as a #define constant from XBPDEV.CH.  Valid
constants have the prefix XBPPRN_DUPLEXMODE_.

COLORMODE <nColorMode> is used to set the color mode for printing.
The mode is selected by a numeric ID which is available as a
#define constant from XBPDEV.CH.  Valid constants have the prefix
XBPPRN_COLORMODE_.

RESOLUTION <nResolution> is used to set the resolution for printing.
The mode is selected by a numeric ID which is available as a
#define constant from XBPDEV.CH.  Valid constants have the prefix
XBPPRN_RESOLUTION_.

MARGIN <anMargin> may be a numeric value or an array of two
numeric values.  If it is a numeric value, then this will be the
value of the left margin.  If it is an array, then the first
element is the TOP margin and the second element is the LEFT
margin.  The margins may be negative and/or decimal values.

TITLE <cTitle> is the title to display in the title bar area of the
Preview window and the Printer Dialog window.   This is also the
name of the print job that is sent to the spooler.

CANCELENABLE will display a dialog window during printing that
includes a CANCEL button to cancel the print job.

AUTOEJECT will cause an automatic page eject whenever an
attempt is made to print past the last print row defined by the
SIZE <nRows>, <nCols> command or whenever an attempt is made to
print to a row that is higher on the page than the last printed
row.  This feature is provided for compatability with existing
Clipper reports.

DIALOGSTYLE <nDialogStyle> allows users of eXPress++ 1.3 and earlier
versions to display the same style dialog in their 1.5 applications
as was displayed in 1.3.  Xbase++ 1.5 introduced a new
XbpPrinterDialog() class which was incorporated in eXPress++ 1.5.
This new dialog is created by the print driver whereas the old
dialog was created by eXPress++ and also included a FONT button for
selecting a print font.  DIALOGSTYLE DCPRINT_DIALOG_EXPRESS will
display the 1.3 style printer dialog.

GRID will print a cross-hatch grid on the paper or preview
window at each text-based row and column defined by the SIZE
clause.  The grid will also include row/column numbers at the
top and left border.  The GRID option will aid in the designing
of reports.

PREVIEW will cause the printed output to be sent to the
display rather than the print device.  The PREVIEW arguments
causes the methods of the DC_PRINTER() class to write to an
XbpDialog() GUI dialog screen rather than to an XbpPrinter()
object.

ZOOMFACTOR <nZoomFactor> is a numeric value to use as the
base for the initial zoom value of the Preview window.  This
clause is used only in PREVIEW mode. The default is 1.0.  A
higher number will cause the text and graphics in the screen
to be larger.  The minimum value is .25.  Numeric values from
0.25 to 4.00 are recommended.  <nZoomIncr> is a numeric value
specifying the zoom resolution.  A smaller number will cause
each click of the ZOOM+/ZOOM- key to have a smaller change.
The default value is .25.

SCROLLFACTOR <nScrollFactor> is used to set the sensitivity of
the scroll bars in the PREVIEW window.  The default is 40.

PPOSITION <nStartCol>, <nStartRow> are the starting coordinates
of the PREVIEW window (in pixels) relative to the left, bottom
of the screen.  The default is 0,0.

PSIZE <nWidth>, <nHeight> is the width and height of the
PREVIEW window (in pixels).  If no size is given then the
window will be automatically sized to fit the screen.

NOSTOP will supress the automatic stop of program execution each
time a DCPRINT EJECT command or oPrinter:eject() method is
encountered in the program.  The control will then be given to
the event loop of the PREVIEW window.  If the NOSTOP clause is
used then the control will only be given to the PREVIEW window
when the command DCPRINT OFF or the function DC_PrinterOff() are
encountered in the program.

HIDE will hide the previewer window until the command DCPRINT OFF
or the function DC_PrinterOff() are encountered in the program.
If the HIDE clause is not used, each page will be visible in
the preview window as they are being created.

NOPRINTBUTTON will remove the 'Print' button from the preview
window, thereby disabling the ability to print while previewing.

BUSYMESSAGE <cBusyMsg> is a message to display while each
screen is being created.  Use this clause if your application
takes a long time to create a screen.

Examples:

#include "dcprint.ch"

FUNCTION XTest()

LOCAL aOptions

DCPRINT OPTIONS ;
   TO aOptions ;
   NOPRINTBUTTON ;
   PSIZE AppDeskTop():currentSize()[1], ;
         AppDeskTop():currentSize()[2] ;
   HIDE ;
   NOSTOP

DC_PrintFile('README.TXT',.t.,nil,aOptions)

RETURN nil

Files:

DCPRINT.CH

See Also:

   DCPRINT ON
   DC_PrintFile()


DCPRINT ORIENTATION

Change the orientation within a print job

DCPRINT ORIENTATION instructs the printer whether to print horizontally or vertically.<br><br>#define constants for <nOrientation><br><br> Constant Description <br><br> XBPPRN_ORIENT_PORTRAIT Prints vertically (portrait) XBPPRN_ORIENT_LANDSCAPE Prints horizontally (landscape) <br><br>This command may be used only after a DCPRINT ENDPAGE and before a DCPRINT STARTPAGE.

Syntax:

DCPRINT ORIENTATION <nOrientation>

Examples:

FUNCTION XTest()

nOrientation := 1

nRows := 60
nCols := 80
cFont := '12.Courier New'

DCPRINT ON
DCPRINT SIZE 60,80
DCPRINT FONT cFont

FOR nPage := 1 TO 4

  @ 2, 10 DCPRINT SAY 'This is Page ' + Alltrim(Str(nPage)) + ;
          IIF(nOrientation=1,' (PORTRAIT - Bin 1)',' (LANDSCAPE - Bin 2)' )

  FOR i := 5 to nRows - IIF( nOrientation=1,10,20)
    cString := ''
    FOR j := 10 TO IIF(nOrientation=1,70,120)
      cString += Alltrim(Str(j%10))
    NEXT
    @ i, 10 DCPRINT SAY cString
  NEXT

  DCPRINT ENDPAGE
  IF nPage % 2 == 0
    nOrientation := 1
    nPaperBin := 1
    nRows := 60
    nCols := 80
    cFont := '12.Courier New'
  ELSE
    nOrientation := 2
    nPaperBin := 2
    nRows := 60
    nCols := 130
    cFont := '9.Courier New'
  ENDIF
  DCPRINT ORIENTATION nOrientation
  DCPRINT PAPERBIN nPaperBin
  DCPRINT SIZE nRows, nCols
  DCPRINT FONT cFont
  DCPRINT STARTPAGE
NEXT

DCPRINT OFF

RETURN nil

Files:

DCPRINT.CH

See Also:

   DCPRINT ENDPAGE


DCPRINT PAPERBIN

Change the paper bin within a print job

DCPRINT PAPERBIN instructs the printer which paper bin to use for a print job. <nBin><br><br>A #define constant from XBPDEV.CH must be used for <nBin> . Valid constants have the prefix XBPPRN_PAPERBIN_. Alternatively, a value obtained via the oPrinter:oDC:paperBins() method can be used. <br><br>This command may be used only after a DCPRINT ENDPAGE and before a DCPRINT STARTPAGE.

Syntax:

DCPRINT PAPERBIN <nBin>

Examples:

FUNCTION XTest()

nOrientation := 1

nRows := 60
nCols := 80
cFont := '12.Courier New'

DCPRINT ON
DCPRINT SIZE 60,80
DCPRINT FONT cFont

FOR nPage := 1 TO 4

  @ 2, 10 DCPRINT SAY 'This is Page ' + Alltrim(Str(nPage)) + ;
          IIF(nOrientation=1,' (PORTRAIT - Bin 1)',' (LANDSCAPE - Bin 2)' )

  FOR i := 5 to nRows - IIF( nOrientation=1,10,20)
    cString := ''
    FOR j := 10 TO IIF(nOrientation=1,70,120)
      cString += Alltrim(Str(j%10))
    NEXT
    @ i, 10 DCPRINT SAY cString
  NEXT

  DCPRINT ENDPAGE
  IF nPage % 2 == 0
    nOrientation := 1
    nPaperBin := 1
    nRows := 60
    nCols := 80
    cFont := '12.Courier New'
  ELSE
    nOrientation := 2
    nPaperBin := 2
    nRows := 60
    nCols := 130
    cFont := '9.Courier New'
  ENDIF
  DCPRINT ORIENTATION nOrientation
  DCPRINT PAPERBIN nPaperBin
  DCPRINT SIZE nRows, nCols
  DCPRINT FONT cFont
  DCPRINT STARTPAGE
NEXT

DCPRINT OFF

RETURN nil

Files:

DCPRINT.CH

See Also:

   DCPRINT ENDPAGE


DCPRINT SIZE

Set the size of the print page in rows and columns

DCPRINT SIZE is used to change the number of print rows and columns (the text-based grid size). This command functions the same as the SIZE clause of the DCPRINT ON command except it allows for changing of the print grid within a single document, to allow for such printing variations as a different grid for the header than for the body of the document.

Syntax:

 DCPRINT SIZE <nRows>, <nCols> ;
    WHEN <bWhen>

Arguments:

<nRows>, <nCols> is the number of print rows and
columns.  The default is 66 rows, 80 columns.

WHEN <bWhen> is a condition codeblock that is evaluated before
the command is executed during previewing and printing from
preview.  The DC_Printer() object is passed to the code block.
The code block must return a logical .TRUE. to enable the command.

Examples:

FUNCTION Xtest()

LOCAL oPrinter, i, j, x

DCPRINT ON TO oPrinter PREVIEW

FOR x := 1 TO 5
  DCPRINT SIZE 40, 80
  DCPRINT FONT '12.Courier New'
  @ 1, 20 DCPRINT SAY 'This is Header Line 1 (Row 1, Col 20)'
  @ 2, 20 DCPRINT SAY 'This is Header Line 2 (Row 2, Col 20)'
  @ 3, 20 DCPRINT SAY 'This is Header Line 3 (Row 3, Col 20)'
  @ 4, 20 DCPRINT SAY 'This is Header Line 4 (Row 4, Col 20)'

  DCPRINT SIZE 66, 132
  DCPRINT FONT '6.Courier New'
  FOR i := 10 TO 40
    FOR j := 1 TO 120 STEP 15
      @ i,j DCPRINT SAY 'Row ' + Str(i,2) + ' Col ' + Alltrim(Str(j,3))
    NEXT
  NEXT
  DCPRINT EJECT
NEXT

DCPRINT OFF

RETURN nil

Files:

DCPRINT.CH

See Also:


DCPRINT STARTPAGE

Start a new Page in a Print Job

DCPRINT STARTPAGE is used to start a new page within a print job. This command is used after a DCPRINT ENDPAGE command. <br><br>After an application uses DCPRINT ENDPAGE to end a page, certain attributes of the print job can be changed before a new page is begun using DCPRINT STARTPAGE . See DCPRINT ENDPAGE for more details.

Syntax:

DCPRINT STARTPAGE

Examples:

FUNCTION XTest()

nOrientation := 1

nRows := 60
nCols := 80
cFont := '12.Courier New'

DCPRINT ON
DCPRINT SIZE 60,80
DCPRINT FONT cFont

FOR nPage := 1 TO 4

  @ 2, 10 DCPRINT SAY 'This is Page ' + Alltrim(Str(nPage)) + ;
          IIF(nOrientation=1,' (PORTRAIT - Bin 1)',' (LANDSCAPE - Bin 2)' )

  FOR i := 5 to nRows - IIF( nOrientation=1,10,20)
    cString := ''
    FOR j := 10 TO IIF(nOrientation=1,70,120)
      cString += Alltrim(Str(j%10))
    NEXT
    @ i, 10 DCPRINT SAY cString
  NEXT

  DCPRINT ENDPAGE
  IF nPage % 2 == 0
    nOrientation := 1
    nPaperBin := 1
    nRows := 60
    nCols := 80
    cFont := '12.Courier New'
  ELSE
    nOrientation := 2
    nPaperBin := 2
    nRows := 60
    nCols := 130
    cFont := '9.Courier New'
  ENDIF
  DCPRINT ORIENTATION nOrientation
  DCPRINT PAPERBIN nPaperBin
  DCPRINT SIZE nRows, nCols
  DCPRINT FONT cFont
  DCPRINT STARTPAGE
NEXT

DCPRINT OFF

RETURN nil

Files:

DCPRINT.CH

See Also:

   DCPRINT ENDPAGE


DCPRINT_Q

Send text to printer using ?/?? style printing

DCPRINT ? prints text at the start column of the next row after the current print row.<br><br> DCPRINT ?? prints text at the current row/column.

Syntax:

DCPRINT ? | ?? <uText> ;
   [PRINTER <oPrinter>] ;
   [WHEN <bWhen>]

Arguments:

<uText> is any variable.

PRINTER <oPrinter> is the printer object returned by the
DCPRINT ON command or the DC_Printer() class.  If this clause
is not used then the printer object referenced by
DC_PrinterObject() is the default.

WHEN <bWhen> is a condition codeblock that is evaluated before
the command is executed during previewing and printing from
preview.  The DC_Printer() object is passed to the code block.
The code block must return a logical .TRUE. to enable the command.

Notes:

The DCPRINT ?/?? command uses the :Qout()/:QQout() methods of the printer object. This method looks at the current ::nPage instance variable and compares it to the ::nFrom value and the ::nTo value. If the current page is outside the range selected by the user, then no output will be sent to the printer.

Examples:

#include 'dcprint.ch'

PROCEDURE XTest( lPreview )

LOCAL nRow, cScrn, aFor_Sale, cFontName, oPrinter, i

lPreview := IIF( Valtype(lPreview)='L',lPreview,.t.)

USE collect NEW
GO TOP

aFor_Sale := { 'No','Yes','Not Sure' }

BEGIN SEQUENCE

IF lPreview
  DCPRINT ON SIZE 50,90 FONT '9.Terminal' TO oPrinter PREVIEW
ELSE
  DCPRINT ON SIZE 50,90 FONT '9.Terminal' TO oPrinter
ENDIF

IF Valtype(oPrinter) # 'O' .OR. !oPrinter:lActive
  BREAK
ENDIF

cFontName := oPrinter:GetFontCompoundName()

IF !lPreview
  cScrn := DC_WaitOn('Printing..')
ENDIF

FOR i := 1 TO oPrinter:nCopies

  GO TOP
  nRow := 1
  oPrinter:nPage := 1
  DO WHILE !Eof()

    IF nRow = 1

      DCPRINT FONT '14.Arial.Bold'

      DCPRINT ? 'My Personal Collection Inventory       '
      DCPRINT ?? 'Page ' + Alltrim(Str(oPrinter:nPage))
      DCPRINT ?? '    '
      DCPRINT ?? Date()
      DCPRINT ?

      nRow += 2

      DCPRINT FONT '12.Arial.Bold'

      DCPRINT ? Pad('Description',35)
      DCPRINT ?? Pad('Type',15)
      DCPRINT ?? Pad('Sub-Type',15)
      DCPRINT ?? Pad('Cond',6)
      DCPRINT ?? Pad('For Sale?',11)
      DCPRINT ?? 'Value'
      DCPRINT ?

      nRow += 2

      DCPRINT FONT cFontName

    ELSE

      DCPRINT ? Pad(COLLECT->descrip,35)
      DCPRINT ?? Pad(COLLECT->type,15)
      DCPRINT ?? Pad(COLLECT->sub_type,15)
      DCPRINT ?? Pad(COLLECT->condition,6)
      DCPRINT ?? Pad(aFor_Sale[COLLECT->for_sale+1],11)
      DCPRINT ?? Str(COLLECT->appr_value,7,2)
      nRow++

      SKIP

      IF nRow > ( oPrinter:nRows - 5 )
        DCPRINT EJECT
        nRow := 1
      ENDIF

    ENDIF

  ENDDO

NEXT

END SEQUENCE

DCPRINT OFF

IF !lPreview
  DC_Impl(cScrn)
ENDIF

CLOSE
RETURN

Files:

DCPRINT.CH

See Also:


DCQDEBUG

Send debug information to a debugging window

DCQDEBUG is used to send data to a debugging window when debugging GUI applications. <br><br> A list of expressions may be included and the output of each expression will be displayed on a new line in the window.<br><br> The debugging window is an object of the XbpMle() class therefore only the last 32000 characters of debug information will be displayed.<br><br> <br><br>

Syntax:

 DCQDEBUG <xExpr1> [ ; <xExprN> ]

Arguments:

<xExpr1> through <xExprN> is any expression.

Notes:

DC_DebugQoutAppendBlock() is a get-set function used to setupadditional information to append to each debug line.

Examples:

 #include "dcdialog.ch"

 USE COLLECT NEW SHARED

 DCQDEBUG Alias(), RecCount()

Files:

DCDIALOG.CH

See Also:

   dc_debugqout()
   dc_debugqoutappendblock()
   dc_qout()
   DCQOUT


DCQDEBUGOFF

Send debug information to a debugging window

DCQDEBUGOFF is used to send data to a debugging window when debugging GUI applications. <br><br> A list of expressions may be included and the output of each expression will be displayed on a new line in the window.<br><br> DCQDEBUGOFF is similar to DCQDEBUG except it will not echo the expression.<br><br>

Syntax:

 DCQDEBUGOFF <xExpr1> [ ; <xExprN> ]

Arguments:

<xExpr1> through <xExprN> is any expression.

Notes:

DC_DebugQoutAppendBlock() is a get-set function used to setupadditional information to append to each debug line.

Examples:

 #include "dcdialog.ch"

 USE COLLECT NEW SHARED

 DCQDEBUGOFF Alias(), RecCount()

Files:

DCDIALOG.CH

See Also:

   dc_debugqout()
   dc_debugqoutappendblock()
   dc_qout()
   DCQOUT


DCQDEBUGOFFQUIET

Send debug information to a debugging window

DCQDEBUGOFFQUIET is used to send data to a debugging window when debugging GUI applications. <br><br> A list of expressions may be included and the output of each expression will be displayed on a new line in the window.<br><br> DCQDEBUGOFFQUIET is similar to DCQDEBUG except it will not echo the expression or the callstack information.<br><br><br><br>

Syntax:

 DCQDEBUGOFFQUIET <xExpr1> [ ; <xExprN> ]

Arguments:

<xExpr1> through <xExprN> is any expression.

Notes:

DC_DebugQoutAppendBlock() is a get-set function used to setupadditional information to append to each debug line.

Examples:

 #include "dcdialog.ch"

 USE COLLECT NEW SHARED

 DCQDEBUGOFFQUIET Alias(), RecCount()

Files:

DCDIALOG.CH

See Also:

   DCQDEBUG


DCQDEBUGQUIET

Send debug information to a debugging window

DCQDEBUGQUIET is used to send data to a debugging window when debugging GUI applications. <br><br> A list of expressions may be included and the output of each expression will be displayed on a new line in the window.<br><br> DCQDEBUGQUIET is similar to DCQDEBUG except it will not echo the callstack information.<br><br><br><br>

Syntax:

 DCQDEBUGQUIET <xExpr1> [ ; <xExprN> ]

Arguments:

<xExpr1> through <xExprN> is any expression.

Notes:

DC_DebugQoutAppendBlock() is a get-set function used to setupadditional information to append to each debug line.

Examples:

 #include "dcdialog.ch"

 USE COLLECT NEW SHARED

 DCQDEBUGQUIET Alias(), RecCount()

Files:

DCDIALOG.CH

See Also:

   DCQDEBUG


DCQOUT

Send data to a debugging window

DCQOUT and DCQQOUT are used to send data to a debugging window window when debugging GUI applications.

Syntax:

DCQOUT | DCQQOUT [ xText ]

Arguments:

<xText> is any variable type.

Examples:

 #include "dcapp.ch"
 #include "dcdialog.ch"

 PROCEDURE Xtest()

 LOCAL GetList := {}, oStatic, oAppEdit

 USE COLLECT NEW SHARED

 DCQOUT Alias(), RecCount()

 @  0,0 DCSTATIC XBPSTATIC_TYPE_RAISEDBOX SIZE 78,7 ;
    GROUP oStatic

 DCAPPEDIT INTO oAppEdit STYLE 3D POSITION 0,0 PARENT oStatic

 DCQOUT COLLECT->descrip

 DCAPPFIELD COLLECT->descrip INTO oAppEdit ;
   CAPTION 'Description' ;
   COLOR GRA_CLR_BLUE

 DCQQOUT COLLECT->type

 DCAPPFIELD COLLECT->type INTO oAppEdit  ;
   CAPTION 'Type'       ;
   COLOR GRA_CLR_BLUE

 DCREAD GUI ;
   FIT ;
   ADDBUTTONS

 RETURN

Files:

DCDIALOG.CH

See Also:

   dc_qoutwindow()
   dc_qout()
   DCQOUT WINDOW
   DCQDEBUG


DCQOUT WINDOW

Establish or Create a CRT window for debugging GUI apps

DCQOUT WINDOW is used to Create a CRT window for debugging GUI applications. The CRT window is used with the DC_Qout() function and DCQOUT command to echo any information. Using the ? command or Qout() function will cause an error if SetAppWindow() is not set to an XbpCrt() object. This makes it very difficult to use ? or Qout() inside GUI applications where SetAppWindow() is pointing to a GUI object like an XbpDialog(). <br><br>

Syntax:

DCQOUT WINDOW  [ oCrt ] ;
   [ EVAL <bEval> ] ;
   [ APPWINDOW ] )

Arguments:

<oCrt> is a pointer to an existing XbpCrt() object to post
as the object for DCQOUT commands.  If no argument is passed
then a new XbpCrt() object will be created.

EVAL <bEval> is a code block to evaluate after the XbpCrt() window
is created.  The Crt object is passed to the code block.

APPWINDOW set the Crt object as the application window with
SetAppWindow().

Examples:

 #include "dcapp.ch"
 #include "dcdialog.ch"

 PROCEDURE Xtest()

 LOCAL GetList := {}, oStatic, oAppEdit

 USE COLLECT NEW SHARED

 DCQOUT WINDOW

 DCQOUT Alias(), RecCount()

 @  0,0 DCSTATIC XBPSTATIC_TYPE_RAISEDBOX SIZE 78,7 ;
    GROUP oStatic

 DCAPPEDIT INTO oAppEdit STYLE 3D POSITION 0,0 PARENT oStatic

 DCQOUT COLLECT->descrip

 DCAPPFIELD COLLECT->descrip INTO oAppEdit ;
   CAPTION 'Description' ;
   COLOR GRA_CLR_BLUE

 DCQQOUT COLLECT->type

 DCAPPFIELD COLLECT->type INTO oAppEdit  ;
   CAPTION 'Type'       ;
   COLOR GRA_CLR_BLUE

 DCREAD GUI ;
   FIT ;
   ADDBUTTONS

 RETURN

Files:

DCDIALOG.CH

See Also:

   dc_qoutwindow()
   dc_qout()


DCREAD GUI

Read the DIALOG GetList with the GUI reader

DCREAD GUI is used to process the Getlist array using the GUI Dialog reader.<br><br> This is the equivalent to DC_ReadGui(). It uses the GetList array of dialogue definitions created by the DC* commands in DCDIALOG.CH, DCDIR.CH, DCAPP.CH and DCTREE.CH. <br><br> An array of DIALOG definitions must exist when using this command and it must have the variable name GETLIST.<br><br>

Syntax:

DCREAD GUI ;
    [TO <lVar>] ;
    [TITLE <cTitle>] ;
    [OPTIONS <aOptions>] ;
    [BUTTONS <nButtons> | ADDBUTTONS ] ;
    [HANDLERBLOCK <bEventHandler>] [HANDLER <HandlerFunc>] ;
      [REFERENCE <xRef>] ;
    [PARENT @<oDlg>] ;
    [OWNER <oOwner>] ;
    [APPWINDOW <oAppWindow>] ;
    [EXIT] ;
    [FIT] ;
    [MODAL] ;
    [EVAL <bEval>] ;
    [SAVE] ;
    [ENTEREXIT] ;
    [NOENTEREXIT] ;
    [ARRAYTRANSLATE] ;
    [SETFOCUS <xObject>] ;
    [GROUP <ancGroup>] ;
    [TIMEOUT <anTimeOut> [NOKEYPRESS]] ;
    [NODESTROY] ;
    [CLEAREVENTS] ;
    [SETAPPWINDOW] ;
    [POSTEVENT <nEvent>] ;
    [MULTILISTS] ;
    [NOAUTORESTORE | NORESTORE] ;
    [AUTORESTORE | RESTORE]

Arguments:

TO <lVar> is a memory variable to store the result of the
dialog when it is exited.  If it was exited with the OK button,
or DC_ReadGuiEvent(DCGUI_EXIT_OK,GetList) then <lVar> will be set
to .TRUE.  If it was exited with the CANCEL button or ESCAPE or
DC_ReadGuiEvent(DCGUI_EXIT_ABORT,GetList) then <lVar> will be set
to .FALSE.

TITLE <cTitle> is the title to display on the top of the dialog
box.

OPTIONS <aOptions> is an array of options for the GUI dialogue
box.  This is ignored if painting text-based GETS.  See
DCDIALOG.CH for a description of this array.

BUTTONS <nButtons> will add extra buttons to the bottom area
of the main dialog window.  <nButtons> is a numeric value
designating the buttons to add based on the below table.
DCDIALOG.CH contains DCGUI_BUTTON_* constant definitions for
the available buttons.  These values are summed to enable multiple
buttons.

Numeric Value       Description
------------------  ---------------------------------------------
DCGUI_BUTTON_OK     Will add a button with the caption OK.
                    Selecting this button will exit the GUI reader
                    and save all changes to their associated
                    memory variables.

DCGUI_BUTTON_CANCEL Will add a button with the caption CANCEL.
                    Selecting this button will exit the GUI reader
                    and restore all memory variables to their
                    original value.

DCGUI_BUTTON_YES    Will add a button with the caption YES.
                    Selecting this button will exit the GUI reader
                    and save all changes to their associated
                    memory variables.

DCGUI_BUTTON_NO     Will add a button with the caption NOL.
                    Selecting this button will exit the GUI reader
                    and restore all memory variables to their
                    original value.

DCGUI_BUTTON_EXIT   Same as DCGUI_BUTTON_OK except the caption is
                    labeled as EXIT.

Optionally, the ADDBUTTONS clause may be used in place of
BUTTONS <nButtons>.  This will paint both the OK and CANCEL
buttons.

NOTE: The added buttons may be aligned left, center or right
      by using the BUTTONALIGN clause of the DCGETOPTIONS command.

HANDLERBLOCK <bEventHandler> is a code block which points
to a custom event handler.  DC_ReadGui() uses it's own, default
event handler to manage the objects during the running of the
program.  The default event handler makes a call to the
custom event handler before processing it's default events.
The custom event handler uses Appevent() to get information
on the current event and passes the following parameters:

 1. nEvent   - The event type.
 2. mp1      - The first event parameter.
 3. mp2      - The second event parameter.
 4. oXbp     - A pointer to the object creating the event.
 5. oDlg     - A pointer to the main dialogue object.
 6. aGetlist - A pointer to the GetList array.
 7. aRef     - A pointer to an optional Reference array that
               was passed to DC_ReadGets().
 8. lOk      - A logical value that is .TRUE. if the OK button
               was clicked and .FALSE. if CANCEL was clicked.

 The Function should look like this:

 STATIC FUNCTION MyHandler ( nEvent, mp1, mp2, oXbp, oDlg,
                             aGetlist, aRef, lOk )

 /* custom code */

 RETURN DCGUI_NONE

The function must return a numeric value which controls the
behavior of the event loop as follows:

 Return Value          Behavior
 ------------          --------------------------------------------
 DCGUI_NONE            Continue processing the event
 DCGUI_IGNORE          Ignore event
 DCGUI_CLEAR           Ignore event and clear all events from queue
 DCGUI_EXIT            Exit the DC_ReadGui() reader event loop
 DCGUI_MOVE_UP         Set focus to previous object in Get List
 DCGUI_MOVE_DOWN       Set focus to next object in Get List
 DCGUI_MOVE_TOP        Set focus to first object in Get List
 DCGUI_MOVE_BOTTOM     Set focus to last object in Get List
 DCGUI_MOVE_UP_PAR     Set focus to previous object in Get List that
                       has the same parent as the current object.
 DCGUI_MOVE_DOWN_PAR   Set focus to next object in Get List that
                       has the same parent as the current object.
 DCGUI_MOVE_TOP_PAR    Set focus to first object in Get List that
                       has the same parent as the current object.
 DCGUI_MOVE_BOTTOM_PAR Set focus to last object in Get List that
                       has the same parent as the current object.
 DCGUI_NOHOTKEY        Don't activate hot key associated with
                       the current object.

As an alternative the clause HANDLER <HandlerFunc> may be used, where
<HandlerFunc> is the name of the function.  The code block will be
created from the function name.

REFERENCE <aRef> is any array or variable to pass to the handler
function.  Programming dialogue systems that must manipulate
many variables is much simpler if all the variables are placed
into a single array and then passed to the dialogue system and
its event handler.  See example 2.

PARENT @<oDialog> is a reference to a parent dialog or to a
memory variable to store a reference to the dialog that will be
created.  If <oDialog> has already been created as an Xbase Parts
class object, it will become the parent for all the objects in
the GetList.  If <oDialog> is passed by reference as a NIL, the
dialog object created by the reader will be stored in this
memory variable.  NOTE: Xbase++ does not allow <oDialog> to be
a PRIVATE or a PUBLIC variable if it is passed by reference.

The parent of the dialog that will be created is referenced by
APPWINDOW <oAppWindow>.  If no <oAppWindow> argument is used
then the parent of the created dialog will be AppDeskTop().

OWNER <oOwner> is the owner of the dialog window.

FIT will automatically form the dialog screen to fit comfortably
around the objects within the dialog.  This option allows the
programmer to use coordinates on dialog objects for relative
addressing only without worrying about how the objects relate to
the borders of the main dialog.  After all the objects are
created, the main dialog borders will be sized to fit the
objects.  The amount of dead space padding is set by using the
FITPAD clause of the DCGETOPTIONS command.  The default is 10
pixels.

CAUTION: Do not use GRASTRING clause of @..DCSAY or DCGRA*
         commands with the FIT clause of DCREAD GUI or the
         AUTOSIZE clause of DCGETOPTIONS, unless the DCGRA*
         object is drawn on an object that does not get resized
         or repositioned at a later time.  Auto-Sizing and
         Auto-Fitting is accomplished by traversing child list
         of the Parent object and reading the size and/or
         coordinates of all objects.  DCGRA* commands are not
         objects, therefore they cannot be repositioned
         correctly.

EXIT will exit the reader after the objects are created and will
not enter the reader's event loop.  It is the responsibility of
the programmer to insure that events are managed and the dialog
is destroyed.  This feature is used to add more objects to an
existing dialog, or to create a dialog that will be managed by
an external event loop.

APPWINDOW <oAppWindow> is the parent object for the main dialog.
If this option is not used then the AppDeskTop() will be used
as the application window.

MODAL will set this dialog modal state to MODAL -
APPLICATION WIDE. If this option is not used, then the dialog
with be NON-MODAL.

NOTE: For MODAL windows to function properly, the calling window
      must be the SetAppWindow().  This can be accomplished quite
      easily by using the EVAL clause of the DCREAD GUI command
      like so:

       DCREAD GUI ;
         FIT ;
         ADDBUTTONS ;
         MODAL ;
         EVAL {|o|SetAppWindow(o)}

EVAL <bEval> is an optional code block to evaluate after all the
objects are created and just before entering the event loop.
Three parameters are passed to the code block: (1) the main dialog
object, (2) the Getlist array, (3) the DC_GetList() object.

SAVE will save the GetList array after returning from the text
or GUI reader.  If the SAVE clause is not used, the GetList
array will be re-initialized to an empty array.

ENTEREXIT will exit the dialog if the ENTER key is pressed.  The
exact behavior is determined by the DC_EnterExitMode() function.
The default behavior is to exit the dialog when the ENTER keys is
pressed in the "last GET".  If this option is not used, then pressing
the ENTER key in the last GET will cause the first GET to receive
focus provided that SET WRAP is ON, otherwise pressing ENTER in the
last GET will have no affect.

The ENTEREXIT clause of DCGETOPTIONS will automatically enable
ENTEREXIT for all dialog windows when use in DC_GetOptDefault().
To disable it for a specific dialog window use the NOENTEREXIT clause.

ARRAYTRANSLATE will translate the HEIGHT, WIDTH, START COLUMN and
START ROW elements in the GETLIST array to pixel coordinates and
write these coordinates back to the original GETLIST array.  It
will also write the translated  Dialog window coordinates to the
GETOPTIONS array and set the TRANSLATE flag in the GETOPTIONS
array to .FALSE.

SETFOCUS <xObject> is the object that receives focus when entering
the event handler. <xObject> may be a type "O" (object), a type
"N" (numeric) or a type "C" character.  If <xObject> is a type "O"
the pass-by-reference operator should be used like so: @<xObject>.
If <xObject> is a type "N" then the numeric value must be a
number from 1 to the length of the GetList.  This is an ordinal
pointer to the GetList item. If <xObject> is a type "C" then the
character string value must be a value equivalent to the ID of
the item in the GetList which is to receive focus.

GROUP <ancGroup> is the GetList group to create.  Each item in
the GetList may be assigned a group name or number via the
GROUP <ancGroup> clause.  If a numeric or character value is
passed then only the items in the GetList which match <ancGroup>
will be created.  <ancGroup> may consist of an array of numeric
values or character values so that more than one group may be
created. If <ancGroup> is a nil then all items in the GetList
will be refreshed.

TIMEOUT <anTimeOut> is used to exit the dialog after a specified
number of seconds.  <anTimeOut> may be a numeric value equivalent
to the number of seconds or an array of two elements as defined
below:

 ELEMENT  TYPE  DESCRIPTION
 -------  ----  ------------------------------------------------
    1       N   The timeout in seconds
    2       B   A code block to execute after the timeout.  The
                code block must return a logical value.  If a .T.
                is returned the exit will occur, otherwise the
                timeout will be reset.

The NOKEYPRESS sub-option will cause the dialog to imeout only if
there is no key pressed within the timeout period.

NODESTROY will preserve the dialog window that is created when
a NIL PARENT clause is used.  By default, this window is
automatically destroyed when exiting the read.

CLEAREVENTS will clear all events from the event queue before
starting up the event loop.  Many times there are many extra
xbeP_Paint events created by DC_ReadGui(), especially when
creating browse screens to insure that all browse objects are
stablized.  If you see a flicker in the screen at startup it
is recommended that you use the CLEAREVENTS clause.

SETAPPWINDOW is important for proper modality.  If your dialog
calls popup windows in validations, popup buttons, etc. you
will want to insure that the called window is MODAL.  If you
use the MODAL clause in the DCREAD GUI command of a popup
window it will not work properly unless the calling window is
the "application window".  This is accomplished with the
SETAPPWINDOW clause.  When returning from DCREAD GUI the
application window will be restored to the previous setting.

POSTEVENT <nEvent> will post an event to the event queue
before starting up the event loop.

MULTILISTS changes the behavior of the event loop slightly so
one event loop can work with multiple GetLists.  This clause
is needed only if the application will be creating new dialogs
or new objects with the DCREAD GUI EXIT command and returning
control to the main event loop.

NOAUTORESTORE or NORESTORE will override DC_AutoRestoreWindow()
default setting and insure that the window coordinates and size
are never saved and restored.

AUTORESTORE or RESTORE will override DC_AutoRestoreWindow()
default setting and insure that the window coordinates and size
are always saved and restored.

Examples:

 -- Example 1 --
/*
This example will display a list of fields in the
"Available Fields" selection, allow the operator to
select a set of fields, then display a Browse of the
database for the fields selected.  The example shows
how to use DCREAD GUI to create a master dialog and
a sub dialog.
*/

#include "dcpick.ch"

PROCEDURE XTest( )

LOCAL GetList := {}, GetOptions, cAlias, aListField, ;
      aPickField, oBrowse, oDialog

USE COLLECT NEW SHARED

cAlias := 'COLLECT'
aListField := Array(FCount())
AFields(aListField)

@ 2,3 DCPICKLIST aPickField LIST aListField ;
   CAPTION "Available Fields", "Selected Fields" ;
   SIZE 35,12 ;
   DATALINK {||BrowseCollect(cAlias,oDialog,@oBrowse,@aPickField)}

DCGETOPTIONS ;
   WINDOWHEIGHT 360 ;
   WINDOWWIDTH 600

DCREAD GUI ;
   TITLE "Picklist Demo" ;
   OPTIONS GetOptions ;
   PARENT @oDialog ;
   ADDBUTTONS

RETURN

/* --------------------- */

STATIC FUNCTION BrowseCollect ( cAlias, oDialog, oBrowse, aPickField )

LOCAL GetList := {}, i, aChildList

IF Valtype(oBrowse) = 'O'
  aChildList := oBrowse:ChildList()
  FOR i := 1 TO Len(aChildList)
    aChildList[i]:Destroy()
  NEXT
  oBrowse:Destroy()
ENDIF

oBrowse := nil

IF Empty(aPickField)
  RETURN nil
ENDIF

@ 2,40 DCBROWSE oBrowse DATA cAlias SIZE 39,12 PARENT oDialog:drawingArea

SELECT collect
FOR i := 1 TO Len(aPickField)
  DCBROWSECOL DATA &('{||COLLECT->'+aPickField[i]+'}') ;
    HEADER aPickField[i] PARENT oBrowse
NEXT

DCREAD GUI ;
   PARENT oDialog ;
   EXIT

oBrowse:hide()
oBrowse:show()

RETURN nil

--- Example 2 ---

This example shows how to use the DCGUI_NOHOTKEY return value
in a custom handler.  Return this value from any custom event
handler to disable the hotkey processing of the event.  This was
added to solve a problem with a customer who used ACCELKEY
parameters of xbeK_CTRL_M (ENTER) and xbeK_CTRL_I (TAB) as hot
keys but wanted the pressing of ENTER and TAB to behave normally
and not activate the hotkey.

aButtons := { xbeK_CTRL_M, {||Ctrl_M_Key()}, ;
              xbeK_CTRL_I, {||Ctrl_I_Key()} }

@ 1,0 DCPUSHBUTTON .. ACTION aButtons[1,2] ACCELKEY aButtons[1,1]
@ 2,0 DCPUSHBUTTON .. ACTION aButtons[2,2] ACCELKEY aButtons[2,1]

bHandler := {|a,b,c,d,e,f,g,h|My_EventHandler(a,b,c,d,e,f,@g,h)}

DCREAD GUI HANDLERBLOCK bHandler

STATIC FUNCTION ;
  My_EventHandler( nEvent, mp1, mp2, oXbp, oDlg, GetList, aButtons )

LOCAL nButton, nKeyState := AppKeyState( xbeK_CTRL )

IF nEvent == xbeP_Keyboard
  nButton := AScan( aButtons, {|a|a[1]==mp1} )
  IF nButton > 0
    IF nKeyState == 1  // Ctrl key down
      Eval( aButtons[nButton,2], nil, nil, oXbp )
      RETURN DCGUI_IGNORE
    ELSE // Ctrl key up
      RETURN DCGUI_NOHOTKEY
    ENDIF
  ENDIF
ENDIF
RETURN DCGUI_NONE

Files:

DCDIALOG.CH

See Also:

   dc_readgui()
   DCGETOPTIONS
   dc_getrefresh()
   dc_enterexitmode()


DCREAD HTML

Read the DIALOG GetList with the HTML reader

DCREAD HTML is used to process the Getlist array using the GUI HTML reader.<br><br> This is the equivalent to DC_ReadHtml(). It uses the GetList array of dialogue definitions created by the DC* commands in DCDIALOG.CH and DCHTML.CH. <br><br> An array of DIALOG definitions must exist when using this command and it must have the variable name GETLIST.<br><br>

Syntax:

DCREAD HTML                                                       ;
      [ TO <cHtml> ]                                                    ;
      [ TITLE <cTitle> ]                                                ;
      [ PARENT <oParent> ]                                              ;
      [ ROOTDIR <cRootDir> ]                                            ;
      [ OBJECT <oHtml> ]                                                ;
      [ MESSAGEINTO <cMessageInto> [TARGET <cTarget>] ]                 ;

Arguments:

TO <cHtml> is a memory variable to store the HTML source
code that is a result of evaluating the GetList.

TITLE <cTitle> is the title to display on the top of the
browser window.

PARENT <oParent> is any parent DC_Html*() object previously
created by DCREAD HTML.

ROOTDIR <cRootDir> is the root directory where other HTML
documents or images reference in the HTML code exist.

OBJECT <oHtmlMain> is the name of a variable to store a
a pointer to the DC_HtmlMain() object created by the HTML
reader.  This object can be stored to a static variable or
state management cargo system to maintain the state of the
application.

MESSAGEINTO <cMessageInto> is the name of a variable that
will be passed in a <a href> tag with the message text of
any object that uses the message clause.  This is activated
when the user clicks on the underlined screen prompt.
TARGET <cTarget> is the name of the Web Browser frame to
invoke the message call.  If this argument is not used,
then a new browser window will be displayed.

variable.

Files:

DCHTML.CH

See Also:

   dc_readhtml()


DCREAD TEXT

Read the DIALOG GetList

DCREAD TEST is used to process the Getlist array using the TEXT Dialog reader.<br><br> This is the equivalent to DC_ReadModal(). It uses the GetList array of dialogue objects created by the DC* commands in DCDIALOG.CH. <br><br> An array of DIALOG definitions must exist when using this command and it must have the variable name GETLIST.<br><br>

Syntax:

DCREAD TEXT ;
    [TITLE <cTitle>] ;
    [TO <lVar>] ;
    [SAVE]

Arguments:

The GetList is passed to DC_READMODAL() - the text reader.

TO <lVar> is a memory variable to store the result of the
dialog when it is exited.  If it was exited with the OK button,
or DC_ReadGuiEvent(DCGUI_EXIT_OK,GetList) then <lVar> will be set
to .TRUE.  If it was exited with the CANCEL button or ESCAPE or
DC_ReadGuiEvent(DCGUI_EXIT_ABORT,GetList) then <lVar> will be set
to .FALSE.

TITLE <cTitle> is the title to display on the top of the dialog
box.

SAVE will save the GetList array and not reinitialize it
to an empty array.

Files:

DCDIALOG.CH

See Also:

   dc_readgets()


DCSETCOLOR

Set the COLOR for successive DC* commands

The command DCSETCOLOR creates a new COLOR definition and adds the definition to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. DCSETCOLOR is used to set the default COLOR to be used for all successive DC* commands when the COLOR clause is not used.

Syntax:

DCSETCOLOR [TO] [<bncColorFG>] [,<ncColorBG>]

Arguments:

<bncColorFG>, <ncColorBG> are foreground and background colors.
They may be character strings representing valid text-based
colors supported by SetColor() or they may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH.

If <bncColorFG> is a code block is must return a 2-element array
containing a foreground and background color.

If the <bncColorFG> clause is not used, then the default color
setting for successive commands will be reset.

Examples:

#include "dcdialog.ch"

PROCEDURE Xtest()

DCSETCOLOR TO GRA_CLR_WHITE, GRA_CLR_BLUE

@ 1,1 DCSAY 'This is white on Blue'
@ 2,1 DCSAY 'This is also white on Blue'

DCSETCOLOR TO GRA_CLR_RED, GRA_CLR_YELLOW

@ 3,1 DCSAY 'This is Red on Yellow'

DCSETCOLOR TO

@ 4,1 DCSAY 'This is normal color (Black on Background)'

DCREAD GUI FIT ADDBUTTONS TITLE 'Example of DCSETCOLOR command'

RETURN nil

Files:

DCDIALOG.CH

See Also:

   DCSETGROUP
   DCSETFONT
   DCSETSAYOPTION


DCSETFONT

Set the FONT for successive DC* commands

The command DCSETFONT creates a new FONT definition and adds the definition to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. DCSETFONT is used to set the default FONT to be used for all successive DC* commands when the FONT clause is not used.

Syntax:

DCSETFONT [TO] [<bocFont>]

Arguments:

<bocFont> is a character string defining an optional
font for successive commands.  The font string must conform to the
Xbase++ standard, ie. "10.Courier.Bold.  It may also be a font
object or a code block that returns a character string or a
font object to later refresh with DC_GetRefresh().

If the <bocFont> clause is not used, then the default font
setting for successive commands will be reset.

Examples:

#include "dcdialog.ch"

PROCEDURE Xtest()

DCSETFONT TO '10.Lucida Console'

@ 1,1 DCSAY 'This is Lucida Console, 10 point'
@ 2,1 DCSAY 'This is also Lucida Console, 10 point'

DCSETFONT TO '12.Arial Bold'

@ 3,1 DCSAY 'This is Arial Bold, 12 point'

DCSETFONT TO

@ 4,1 DCSAY 'This is normal font (8.Arial)'

DCREAD GUI FIT ADDBUTTONS TITLE 'Example of DCSETFONT command'

RETURN nil

Files:

DCDIALOG.CH

See Also:

   DCSETCOLOR
   DCSETGROUP
   DCSETSAYOPTION


DCSETGROUP

Set the GROUP name for successive DC* commands

The command DCSETGROUP creates a new GROUP definition and adds the definition to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. DCSETGROUP is used to set the default GROUP name to be used for all successive DC* commands when the GROUP clause is not used.

Syntax:

DCSETGROUP [TO] [<cGroup>]

Arguments:

TO <cGroup> is the name of the group.

Examples:

#include "dcdialog.ch"

PROCEDURE Xtest()

LOCAL oTabPage1, oTabPage2, GetList := {}

@ 1,1 DCTABPAGE oTabPage1 CAPTION 'Page 1' SIZE 50,10

DCSETPARENT TO oTabPage1
DCSETGROUP TO 'PAGE1'

@ 2,2 DCSAY 'This goes on Tab Page ONE'
@ 4,2 DCSAY 'This goes on Tab Page ONE too!'
@ 6,2 DCSAY 'This goes on Tab Page ONE too!'

DCSETPARENT TO
DCSETGROUP TO

@ 0,0 DCTABPAGE oTabPage2 CAPTION 'Page 2' RELATIVE oTabPage1

DCSETPARENT TO oTabPage2
DCSETGROUP TO 'PAGE2'

@ 2,2 DCSAY 'This goes on Tab Page TWO'
@ 4,2 DCSAY 'This goes on Tab Page TWO too!'
@ 6,2 DCSAY 'This goes on Tab Page TWO too!'

DCREAD GUI FIT ADDBUTTONS TITLE 'Example of DCSETGROUP command'

RETURN nil

Files:

DCDIALOG.CH

See Also:

   DC_GetRefresh()


DCSETPARENT

Set the Parent object for successive DC* commands

The command DCSETPARENT creates a new Parent object definition adds the definition to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. DCSETPARENT is used to set the default object to be used for all successive DC* commands when the PARENT clause is not used.

Syntax:

DCSETPARENT [TO] [<oParent>]

Arguments:

TO <oParent> is the variable that points to the object to set as
the default parent.  If this parameter is not used, then the
parent is set to the main dialog window.

Examples:

#include "dcdialog.ch"

PROCEDURE Xtest()

LOCAL oTabPage1, oTabPage2, GetList := {}

@ 1,1 DCTABPAGE oTabPage1 CAPTION 'Page 1' SIZE 50,10

DCSETPARENT TO oTabPage1

@ 2,2 DCSAY 'This goes on Tab Page ONE'
@ 4,2 DCSAY 'This goes on Tab Page ONE too!'
@ 6,2 DCSAY 'This goes on Tab Page ONE too!'

DCSETPARENT TO

@ 0,0 DCTABPAGE oTabPage2 CAPTION 'Page 2' RELATIVE oTabPage1

DCSETPARENT TO oTabPage2

@ 2,2 DCSAY 'This goes on Tab Page TWO'
@ 4,2 DCSAY 'This goes on Tab Page TWO too!'
@ 6,2 DCSAY 'This goes on Tab Page TWO too!'

DCREAD GUI FIT ADDBUTTONS TITLE 'Example of DCSETPARENT command'

RETURN nil

Files:

DCDIALOG.CH


DCSETRESIZE

Set the RESIZE method for successive DC* commands

The command DCSETRESIZE creates a new RESIZE definition and adds the definition to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. DCSETRESIZE is used to set the default RESIZE method to be used for all successive DC* commands when the RESIZE clause is not used.<br><br>This command creates a resize callback to use DC_Resize() as the function for resizing and repositioning child objects after the parent window has been resized. Most DC* commands include a RESIZE clause to establish the rules for how the object associated with that command will be resized and/or repositioned.

Syntax:

DCSETRESIZE TO [<aResize>]

Arguments:

<aResize> is an an array of two elements:

The first element is an optional code block that must return
two numeric values which will be the new X and Y position of
the object after its parent has been resized.  The code block
is passed two numeric arguments equivalent to the X delta and
the Y delta of the parent after it has been resized.  The second
element is an optional code block that must return two numeric
values which will be the new X and Y size of the object after
its parent has been resized.  The code block is passed two
numeric arguments equivalent to the X delta and the Y delta of
the parent after it has been resized.

Examples:

DCSETRESIZE { {|x,y,o|{ o:currentPos()[1], o:currentPos()[2] + y} },;
              {|x,y,o|{ o:currentSize()[1] + x, o:currentSize()[2] + y} } }

DCSETRESIZE DCGUI_RESIZE_AUTORESIZE

DCSETRESIZE DCGUI_RESIZE_REPOSONLY_Y

Note: DCDIALOG.CH contains DCGUI_RESIZE_* constants for commonly used
      resizing rules.

If the <aResize> clause is not used, then the default resize
method for successive commands will be reset to the value
established by DCGETOPTIONS..RESIZEDEFAULT.

Examples:

#include "dcdialog.ch"

PROCEDURE Xtest()

LOCAL GetList[0], GetOptions

DCSETRESIZE TO DCGUI_RESIZE_REPOSONLY_Y

@ 1,1 DCSAY 'This will move up when the window is resized vertically'

DCSETRESIZE TO DCGUI_RESIZE_REPOSONLY

@ 3,1 DCSAY 'This will move up and to the right when window is enlarged'

DCSETRESIZE TO

@ 4,1 DCMULTILINE cText SIZE 40,10 // resize both directions

DCGETOPTIONS RESIZE RESIZEDEFAULT DCGUI_RESIZE_RESIZEONLY ;
  SAYWIDTH 0

DCREAD GUI FIT ADDBUTTONS ;
  TITLE 'Example of DCSETFONT command' ;
  OPTIONS GetOptions

RETURN nil

Files:

DCDIALOG.CH

See Also:

   DCGETOPTIONS
   DCSETCOLOR
   DCSETGROUP
   DCSETSAYOPTION
   DCSETFONT


DCSETSAYOPTION

Set the text alignment options for successive DCSAY commands

The command DCSETSAYOPTION creates a new text alignment definition and adds the definition to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. DCSETSAYOPTION is used to set the default text alignment option to be used for all successive DCSAY and DCSAY..GET commands when the OPTION clause is not used.

Syntax:

DCSETSAYOPTION [TO] [<nSayOpt>]

Arguments:

<nSayOpt> is a set of options that can be used to
align the text within the rectangular area of the SAY object.
Constants defined in the XBP.CH file are used for these options.
If combinations of alignment options are required, the sum of
the appropriate constants must be included in <nSayOpt>.
The below constants are defined in XBP.CH.

 XBPSTATIC_TEXT_LEFT       Text is left aligned
 XBPSTATIC_TEXT_CENTER     Text is horizontally centered
 XBPSTATIC_TEXT_RIGHT      Text is right aligned
 XBPSTATIC_TEXT_TOP        Text is displayed at top
 XBPSTATIC_TEXT_VCENTER    Text is vertically centered
 XBPSTATIC_TEXT_BOTTOM     Text is displayed at bottom
 XBPSTATIC_TEXT_WORDBREAK  Text is wrapped (multi-line)

If the <nSayOpt> clause is not used, then the default option
setting for successive commands will be reset.

Examples:

#include "dcdialog.ch"

PROCEDURE Xtest()

LOCAL GetList[0], GetOptions

DCSETSAYOPTION TO XBPSTATIC_TEXT_RIGHT

@ 1,1 DCSAY 'This is aligned right'
@ 2,1 DCSAY 'This is also aligned right'

DCSETSAYOPTION TO XBPSTATIC_TEXT_LEFT

@ 3,1 DCSAY 'This is aligned left'

DCSETSAYOPTION TO

@ 4,1 DCSAY 'This is normal alignment (left bottom)'

DCGETOPTIONS SAYWIDTH 400 SAYLEFTBOTTOM

DCREAD GUI FIT ADDBUTTONS ;
  TITLE 'Example of DCSETSAYOPTION command' ;
  OPTIONS GetOptions

RETURN nil

Files:

DCDIALOG.CH

See Also:

   DCSETCOLOR
   DCSETGROUP
   DCSETFONT


DCSTATUSBAR

Create a Status Bar area on the perimiter of a dialog

DCSTATUSBAR is used to create areas around the perimiter of the a dialog window that are automatically resized when the dialog is resized and are children of the main XbpDialog() object rather than the drawingArea. This allows for toolbars, message areas, progress bars, etc that are anchored to the main dialog window and cannot be hidden by other child windows.<br><br>A single dialog may have multiple status bars. Each status bar can be individually hidden from view which will shift all other status bars to the top, bottom, etc. The status bar is a window of the XbpStatic() type class and can be the parent of any other type of DC* object.<br><br>

Syntax:

DCSTATUSBAR <oObject>          ;
      [TYPE <nType>]           ;
      [ALIGN <nAlign>]         ;
      [HEIGHT <nHeight>]       ;
      [WIDTH <nWidth>]         ;
      [SPACING <nSpacing>]     ;
      [CARGO <xCargo>]         ;
      [PRESENTATION <aPres>]   ;
      [PREEVAL <bPreEval>] ;
      [EVAL <bEval>]           ;
      [TITLE <cTitle>]         ;
      [HIDE <bHide>]           ;
      [ID <cId>]               ;
      [GROUP <cGroup>]         ;
      [COLOR <nFG>, <nBG>]     ;
      [ANCHOR <nAnchor>]       ;

Arguments:

<oStatus> is the name of the variable to assign as a storage
place for this object.

TYPE <nType> is the type of status bar.  Status Bars are created
using XbpStatic() objects, so valid constants start with the
prefix XBPSTATIC_TYPE_ and are listed in XBP.CH.  The default
is XBPSTATIC_TYPE_RAISEDBOX.

ALIGN <nAlign> is a numeric constant defined in DCDIALOG.CH.

DCGUI_ALIGN_TOP    - Attach statusbar to top of window
DCGUI_ALIGN_BOTTOM - Attach statusbar to bottom of window
DCGUI_ALIGN_RIGHT  - Attach statusbar to right side of window
DCGUI_ALIGN_LEFT   - Attach statusbar to left side of window

HEIGHT <nHeight> is the height (in pixels) of the status bar if
it has a top or bottom alignment.  This clause is ignored if the
status bar has a left or right alignment.

WIDTH <nWidth> is the width (in pixels) of the status bar if
it has a left or right alignment.  This clause is ignored if the
status bar has a top or bottom alignment.

SPACING <nSpacing> is the number of pixels between child objects
on the status bar.  The default is 3 pixels.  When a child object
is placed on a top or bottom status bar, only the <row> address
is significant because this determines the vertical location of
the object on the status bar.  The <column> address is ignored
because the object is placed to the right of the previous child
object spaced by <nSpacing> pixels.  When a child object is
placed on a left or right status bar, only the <column> address
is significant because this determines the horizontal location
of the object on the status bar.  The <row> address is ignored
because the object is below the previous child object spaced by
<nSpacing> pixels.

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the Statusbar object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Status Bar object is created.  The object is passed
to the code block.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the status bar will be hidden from view.  If
the value returned is .FALSE. then the status bar will be displayed.
The object is passed as a parameter to the code block.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETOBJECT() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

COLOR <nFG>, <nBG> are foreground and background colors for the
statusbar.

ANCHOR <nAnchor> is an option that is used to anchor child items
to the left rather than the right (default) side of the status bar.

Ex. ..ANCHOR DCGUI_ALIGN_LEFT

Examples:

/*
This example demonstrates status bars of all four alignment
styles in an MDI application.  The first status bar is used as
a toolbar with buttons to HIDE or SHOW the other status bars.
*/

FUNCTION XTest()

LOCAL GetList := {}, GetOptions, oMenuBar, oFileMenu, oToolBottom, ;
      oDlg, oDrawingArea, oStatBottom, bReSize, oMsgBox, oProgress, ;
      oMsgStatic, lTesting := .f., oInsStatic, oNumStatic, ;
      oCapsStatic, oStatTop, oToolTop, oStatTop2, oToolTop2, ;
      lHideStatus2 := .f., lHideStatus3 := .f., lHideStatus4 := .f., ;
      lHideStatus5 := .f., oStatLeft1, oStatLeft2, oStatRight1, ;
      oToolLeft1, oToolleft2, oToolRight1, oProgressStatic, ;
      oStatRight2, oToolRight2, lHideStatus6 := .f., lHideStatus7 := .f.

DCMENUBAR oMenuBar

  DCSUBMENU oFileMenu CAPTION 'File' ;
    MESSAGE 'File Options' INTO oMsgBox ;
    PARENT oMenuBar

    DCMENUITEM CAPTION 'Browse' ;
      MESSAGE 'Browse the Documentation Database' ;
      INTO oMsgBox ;
      PARENT oFileMenu ;
      ACTION {|o|o:=Thread():new(), ;
              o:start({||BrowseWindow(oDlg:drawingArea,oMsgBox,;
                         oProgress,@lTesting,GetList)}) }

    DCMENUITEM CAPTION 'Exit' ;
      MESSAGE 'Quit this Program' INTO oMsgBox ;
      PARENT oFileMenu ;
      ACTION {||DC_ReadGuiEvent(DCGUI_EXIT_OK,GetList)}

// Top Statusbar #1 with Toolbar
DCSTATUSBAR oStatTop HEIGHT 20 ALIGN DCGUI_ALIGN_TOP SPACING 0

@ 0,0 DCTOOLBAR oToolTop SIZE 400,20 BUTTONSIZE 100,20 ;
      TYPE XBPSTATIC_TYPE_RAISEDBOX PARENT oStatTop PIXEL

DCADDBUTTON CAPTION 'Top ToolBar 2' ;
  ACTION {||lHideStatus2 := !lHideStatus2, ;
            DC_GetRefresh(GetList), ;
            DC_StatusBarRePaint(oDlg)} ;
  PARENT oToolTop PIXEL

DCADDBUTTON CAPTION 'Bottom StatusBar' ;
  ACTION {||lHideStatus3 := !lHideStatus3, ;
            DC_GetRefresh(GetList), ;
            DC_StatusBarRePaint(oDlg)} ;
  PARENT oToolTop PIXEL

DCADDBUTTON CAPTION 'Left ToolBar #1' ;
  ACTION {||lHideStatus4 := !lHideStatus4, ;
            DC_GetRefresh(GetList), ;
            DC_StatusBarRePaint(oDlg)} ;
  PARENT oToolTop PIXEL

DCADDBUTTON CAPTION 'Left ToolBar #2' ;
  ACTION {||lHideStatus5 := !lHideStatus5, ;
            DC_GetRefresh(GetList), ;
            DC_StatusBarRePaint(oDlg)} ;
  PARENT oToolTop PIXEL

DCADDBUTTON CAPTION 'Right ToolBar #1' ;
  ACTION {||lHideStatus6 := !lHideStatus6, ;
            DC_GetRefresh(GetList), ;
            DC_StatusBarRePaint(oDlg)} ;
  PARENT oToolTop PIXEL

DCADDBUTTON CAPTION 'Right ToolBar #2' ;
  ACTION {||lHideStatus7 := !lHideStatus7, ;
            DC_GetRefresh(GetList), ;
            DC_StatusBarRePaint(oDlg)} ;
  PARENT oToolTop PIXEL

// Top Statusbar #2 (Hideable) with toolbar
DCSTATUSBAR oStatTop2 HEIGHT 20 ALIGN DCGUI_ALIGN_TOP ;
   HIDE {||lHideStatus2}

@ 0,0 DCTOOLBAR oToolTop2 SIZE 400,20 BUTTONSIZE 50,20 ;
      TYPE XBPSTATIC_TYPE_RAISEDBOX PARENT oStatTop2 PIXEL

DCADDBUTTON CAPTION 'Button4' ;
  ACTION {||DC_ReadGuiEvent(DCGUI_EXIT_OK,GetList)} ;
  PARENT oToolTop2 PIXEL

DCADDBUTTON CAPTION 'Button5' ;
  ACTION {||DC_ReadGuiEvent(DCGUI_EXIT_OK,GetList)} ;
  PARENT oToolTop2 PIXEL

DCADDBUTTON CAPTION 'Button6' ;
  ACTION {||DC_ReadGuiEvent(DCGUI_EXIT_OK,GetList)} ;
  PARENT oToolTop2 PIXEL

// Bottom Statusbar (Hideable) with message, scrollbar, buttons, key status
DCSTATUSBAR oStatBottom HEIGHT 28 ALIGN DCGUI_ALIGN_BOTTOM ;
   HIDE {||lHideStatus3}

@ 3,0 DCSTATIC TYPE XBPSTATIC_TYPE_RECESSEDBOX ;
      SIZE 300,20 ;
      PARENT oStatBottom PIXEL OBJECT oMsgStatic

@ 2,2 DCMESSAGEBOX TYPE XBPSTATIC_TYPE_TEXT ;
      SIZE 300,20 MOTION ;
      COLOR GRA_CLR_BLUE, GRA_CLR_BACKGROUND ;
      OBJECT oMsgBox PARENT oMsgStatic PIXEL

@ 3,0 DCSTATIC TYPE XBPSTATIC_TYPE_RECESSEDBOX ;
      OBJECT oProgressStatic ;
      SIZE 100,20 PARENT oStatBottom PIXEL

@ 2,3 DCPROGRESS oProgress ;
      COLOR GRA_CLR_DARKRED, GRA_CLR_BACKGROUND ;
      TYPE XBPSTATIC_TYPE_TEXT ;
      SIZE 96,16 PARENT oProgressStatic PIXEL

@ 3,0 DCTOOLBAR oToolBottom SIZE 126,20 BUTTONSIZE 40,20 ;
      TYPE XBPSTATIC_TYPE_RECESSEDBOX PARENT oStatBottom PIXEL

DCADDBUTTON CAPTION '&Exit' ;
  ACTION {||DC_ReadGuiEvent(DCGUI_EXIT_OK,GetList)} ;
  PARENT oToolBottom PIXEL

DCADDBUTTON TYPE XBPSTATIC_TYPE_RAISEDBOX SIZE 3,22 ;
  PARENT oToolBottom PIXEL

DCADDBUTTON CAPTION '&Cancel' ;
  ACTION {||lTesting := .f.} ;
  WHEN {||lTesting} ;
  PARENT oToolBottom PIXEL

DCADDBUTTON TYPE XBPSTATIC_TYPE_RAISEDBOX SIZE 3,22 ;
  PARENT oToolBottom PIXEL

DCADDBUTTON CAPTION '&Browse' ;
  PARENT oToolBottom ;
  ACTION {|o|o:=Thread():new(), ;
    o:start({||BrowseWindow(oDlg:drawingArea,oMsgBox:ChildList()[1], ;
                oProgress,@lTesting,GetList)}) } ;
  PIXEL

@ 3,0 DCSTATIC TYPE XBPSTATIC_TYPE_RECESSEDBOX ;
      SIZE 30,20 PARENT oStatBottom PIXEL OBJECT oCapsStatic

@ 1,1 DCSAY '' PARENT oCapsStatic ID 'CAPSLOCK' ;
      SAYSIZE 28,18 SAYCENTER PIXEL

@ 3,0 DCSTATIC TYPE XBPSTATIC_TYPE_RECESSEDBOX ;
      SIZE 30,20 PARENT oStatBottom PIXEL OBJECT oNumStatic

@ 1,1 DCSAY '' PARENT oNumStatic ID 'NUMLOCK' ;
      SAYSIZE 28,18 SAYCENTER PIXEL

@ 3,0 DCSTATIC TYPE XBPSTATIC_TYPE_RECESSEDBOX ;
      SIZE 30,20 PARENT oStatBottom PIXEL OBJECT oInsStatic

@ 1,1 DCSAY '' PARENT oInsStatic ID 'INSERT' ;
      SAYSIZE 28,18 SAYCENTER PIXEL

// Left Statusbar #1 (Hideable) with toolbar
DCSTATUSBAR oStatLeft1 WIDTH 45 ALIGN DCGUI_ALIGN_LEFT ;
   HIDE {||lHideStatus4} TYPE XBPSTATIC_TYPE_TEXT

@ 0,0 DCTOOLBAR oToolLeft1 SIZE 45,1000 BUTTONSIZE 45,20 ;
      TYPE XBPSTATIC_TYPE_RAISEDBOX PARENT oStatLeft1 PIXEL

DCADDBUTTON CAPTION '1-Test1' PARENT oToolLeft1 PIXEL
DCADDBUTTON CAPTION '1-Test2' PARENT oToolLeft1 PIXEL
DCADDBUTTON CAPTION '1-Test3' PARENT oToolLeft1 PIXEL
DCADDBUTTON CAPTION '1-Test4' PARENT oToolLeft1 PIXEL

// Left Statusbar #2 (Hideable) with toolbar
DCSTATUSBAR oStatLeft2 WIDTH 45 ALIGN DCGUI_ALIGN_LEFT ;
   HIDE {||lHideStatus5} TYPE XBPSTATIC_TYPE_TEXT

@ 0,0 DCTOOLBAR oToolLeft2 SIZE 45,1000 BUTTONSIZE 45,20 ;
      TYPE XBPSTATIC_TYPE_RAISEDBOX PARENT oStatLeft2 PIXEL

DCADDBUTTON CAPTION '2-Test1' PARENT oToolLeft2 PIXEL
DCADDBUTTON CAPTION '2-Test2' PARENT oToolLeft2 PIXEL
DCADDBUTTON CAPTION '2-Test3' PARENT oToolLeft2 PIXEL
DCADDBUTTON CAPTION '2-Test4' PARENT oToolLeft2 PIXEL

// Right Statusbar #1 (Hideable) with toolbar
DCSTATUSBAR oStatRight1 WIDTH 30 ALIGN DCGUI_ALIGN_RIGHT ;
   HIDE {||lHideStatus6} TYPE XBPSTATIC_TYPE_TEXT

@ 0,0 DCTOOLBAR oToolRight1 SIZE 30,1000 BUTTONSIZE 30,25 ;
      TYPE XBPSTATIC_TYPE_RAISEDBOX PARENT oStatRight1 PIXEL

DCADDBUTTON CAPTION BITMAP_EXECUTE_M PARENT oToolRight1 PIXEL
DCADDBUTTON CAPTION BITMAP_UNDO_M PARENT oToolRight1 PIXEL
DCADDBUTTON CAPTION BITMAP_REDO_M PARENT oToolRight1 PIXEL
DCADDBUTTON CAPTION BITMAP_BOLD_M PARENT oToolRight1 PIXEL
DCADDBUTTON CAPTION BITMAP_ITALIC_M PARENT oToolRight1 PIXEL
DCADDBUTTON CAPTION BITMAP_UNDERLINE_M PARENT oToolRight1 PIXEL
DCADDBUTTON CAPTION BITMAP_CODEWRITE_M PARENT oToolRight1 PIXEL
DCADDBUTTON CAPTION BITMAP_CONFIG_M PARENT oToolRight1 PIXEL
DCADDBUTTON CAPTION BITMAP_DESIGN_M PARENT oToolRight1 PIXEL
DCADDBUTTON CAPTION BITMAP_COMMENT_M PARENT oToolRight1 PIXEL

// Right Statusbar #2 (Hideable) with toolbar
DCSTATUSBAR oStatRight2 WIDTH 30 ALIGN DCGUI_ALIGN_RIGHT ;
   HIDE {||lHideStatus7} TYPE XBPSTATIC_TYPE_TEXT

@ 0,0 DCTOOLBAR oToolRight2 SIZE 30,1000 BUTTONSIZE 30,25 ;
      TYPE XBPSTATIC_TYPE_RAISEDBOX PARENT oStatRight2 PIXEL

DCADDBUTTON CAPTION BITMAP_BROWSER_M PARENT oToolRight2 PIXEL
DCADDBUTTON CAPTION BITMAP_CHECKBOX_M PARENT oToolRight2 PIXEL
DCADDBUTTON CAPTION BITMAP_LISTBOX_M PARENT oToolRight2 PIXEL
DCADDBUTTON CAPTION BITMAP_DIALOG_M PARENT oToolRight2 PIXEL
DCADDBUTTON CAPTION BITMAP_EDIT_M PARENT oToolRight2 PIXEL
DCADDBUTTON CAPTION BITMAP_SPINBUTTON_M PARENT oToolRight2 PIXEL
DCADDBUTTON CAPTION BITMAP_MLE_M PARENT oToolRight2 PIXEL
DCADDBUTTON CAPTION BITMAP_GET_M PARENT oToolRight2 PIXEL

DCHOTKEY xbeK_INS ACTION {||ReadInsert(!ReadInsert())}

DCGETOPTIONS WINDOWWIDTH 610 ;
             WINDOWHEIGHT 400

DCREAD GUI OPTIONS GetOptions ;
   PARENT @oDlg ;
   TITLE 'Status Bar Example' ;
   EVAL {|o|SetTimerEvent(100,{||_UpdateStats(GetList)}) }

SetTimerEvent(0)

RETURN nil

* ------------------

STATIC FUNCTION _UpdateStats( GetList )

LOCAL oCapsLock := DC_GetObject(GetList,'CAPSLOCK')
LOCAL oNumLock  := DC_GetObject(GetList,'NUMLOCK')
LOCAL oInsert   := DC_GetObject(GetList,'INSERT')
LOCAL lCaps     := AppKeystate( VK_CAPITAL, .T. )
LOCAL lNum      := AppKeystate( VK_NUMLOCK, .T. )

IF lNum == APPKEY_PRESSED
  oNumlock:SetCaption( "Num" )
ELSE
  oNumlock:SetCaption( "" )
ENDIF
IF lCaps == APPKEY_PRESSED
  oCapslock:SetCaption( "Caps" )
ELSE
  oCapslock:SetCaption( "" )
ENDIF
IF ReadInsert()
  oInsert:SetCaption( "Ins" )
ELSE
  oInsert:SetCaption( "Ovr" )
ENDIF

RETURN nil

* ------------

STATIC FUNCTION BrowseWindow( oDlg, oMsgBox, oProgress, ;
                lTesting, aMainGetList )

LOCAL GetList := {}, oBrowse, GetOptions

IF !File('..\XDOC\EXPRESS.DBF')
  DC_MsgBox({'Sorry.  The database required to show this feature',;
             'is not included in the demonstration version', ;
             'or the ..\XDOC\EXPRESS.DBF file does not exist'})
  RETURN nil
ENDIF

SET DEFA TO ..\XDOC
USE EXPRESS VIA FOXCDX SHARED ALIAS 'XDOC'
SET INDEX TO EXPRESS.CDX
OrdSetFocus('COMMAND')
SET DEFA TO

@ 0,0 DCSAY ''
@ 1,0 DCBROWSE oBrowse ALIAS 'XDOC' SIZE 50, 8

DCBROWSECOL DATA {||XDOC->command} HEADER 'Command' ;
   PARENT oBrowse ;
   MESSAGE 'This is the Command, Function or Class' ;
   INTO oMsgBox

DCBROWSECOL DATA {||XDOC->short} HEADER 'Short' ;
   PARENT oBrowse ;
   MESSAGE 'This is the Short Description' ;
   INTO oMsgBox

DCBROWSECOL DATA {||XDOC->type} HEADER 'Type' ;
   PARENT oBrowse ;
   MESSAGE 'This is the Type of Help Item' ;
   INTO oMsgBox

DCBROWSECOL DATA {||XDOC->module} HEADER 'Module' ;
   PARENT oBrowse ;
   MESSAGE 'This is the name of the Module containing this item' ;
   INTO oMsgBox

DCBROWSECOL DATA {||XDOC->see_also} HEADER 'See Also' ;
   PARENT oBrowse ;
   MESSAGE 'This is a list of related items' ;
   INTO oMsgBox

@ 9.5,40 DCPUSHBUTTON CAPTION 'Test' SIZE 10,1.2 ;
  TOOLTIP 'Test all the records in the database' ;
  WHEN {||!lTesting} ;
  TITLE 'eXPress++ Documentation' ;
  ACTION {||_TestRecords(oMsgBox,oProgress,@lTesting,aMainGetList)}

DCHOTKEY xbeK_INS ACTION {||ReadInsert(!ReadInsert())}

DCGETOPTIONS ;
   AUTORESIZE ;
   WINDOWCOL 5 ;
   CASCADE

DCREAD GUI FIT ;
   OPTIONS GetOptions ;
   APPWINDOW oDlg ;
   TITLE 'eXPress++ Help File'

RETURN nil

* -------------

STATIC FUNCTION _TestRecords( oMsgBox, oProgress, lTesting, aMainGetList )

LOCAL nRecNo := RecNo(), nCount

lTesting := .t.
DC_GetRefresh(aMainGetList)
oMsgBox:setCaption('Test in Progress...')
GO TOP
nCount := 0
DO WHILE !Eof() .AND. lTesting
  DC_AppEvent(@lTesting,0,.01)
  DC_GetProgress( oProgress, nCount++, RecCount() )
  Sleep(1)
  // .. put test code here
  SKIP
ENDDO
oMsgBox:setCaption('Test Completed!  No Errors!')

DC_GetProgress( oProgress, -1, 0 ) // Clear progress box

GO nRecNo
lTesting := .f.
DC_GetRefresh(aMainGetList)

RETURN nil

Files:

DCDIALOG.CH

See Also:

   DCPANEL


DCSUBMENU

Add Submenu to MENUBAR object for displaying with Text/GUI reader

The command DCSUBMENU creates a new SubMenu definition and adds the definition to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> DCSUBMENU is used with the DCMENUBAR command to add pull-down menus to a MenuBar object or with the DCTREEROOT / DCTREEITEM commands to add tree branches to a Treeview object.

Syntax:

DCSUBMENU <oSubMenu> ;
    [PROMPT <bcPrompt>] ;
    [INDEX <nIndex>] ;
    [PARENT <oParent>] ;
    [PARENT <cParentId>] ;
    [WHEN <bWhen>] ;
    [ACTION <bAction>] ;
    [ACTIVATEITEM <bActivate>] ;
    [NAME <nName>] ;
    [CHECKED] ;
    [CHECKWHEN <bCheckWhen>] ;
    [SEPARATOR] ;
    [STYLE <nStyle>] ;
    [ATTRIBUTE <nAttr>] ;
    [HELPCODE <cHelpCode>] ;
    [LOCK <cLock>] ;
    [CARGO <xCargo>] ;
    [ACCELKEY <nAccelKey>] ;
    [ID <cId>] ;
    [PRESENTATION <aPres>] ;
    [PREEVAL <bPreEval>] ;
    [EVAL <bEval>] ;
    [TITLE <cTitle>] ;
    [GROUP <cGroup>] ;
    [MESSAGE <bcMsg> [INTO <oMsgBox>]] ;
    [LOCK <cLock>] ;
    [PROTECT <bProtect>] ;
    [OWNERDRAW] ;
    [BARTEXT <cBarText>] ;
    [BARFONT <cBarFont>] ;
    [FGCOLOR <anFGColor>] ;
    [BGCOLOR <anBGColor>] ;
    [BARCOLOR <anBarColorFG>,<anBarColorBG>] ;
    [ITEMFONT <cItemFont>] ;
    [BEGINMENU <bBeginMenu>] ;
    [ENDMENU <bEndMenu>] ;
    [ITEMMARKED <bItemMarked>] ;
    [ITEMSELECTED <bItemSelected>] ;
    [SUBITEMFONT <cSubItemFont>] ;
    [COLUMNBREAK]

Arguments:

<oSubMenu> is the name of the variable to assign to the
object.

PROMPT <bcPrompt> is the caption to assign to this menu item.
The caption may be a character string, a resource number for
a bitmap, another XbpMenu() object,  a NIL (for separator
bars), or a code block.  If the caption is a character string,
it may include a Tilde (~) character to define the hot-key for the item
like so: "Save ~Changes". If <bcPrompt> is a code-block, then
it must return a character string, a resource number or an
XbpMenu() object.  This code block will be evaluated whenever
the function DC_GetRefresh() or DC_GetWhen() is called.

ACTION <bAction> is a code block that gets evaluated when
the menu item is selected.  Do not use this clause if
the submenu has menu items.

ACTIVATEITEM <bActivate> is a code block to run in lieu of using
ACTION clauses on child DCMENUITEM commands.  <bActivate> can be
used to run an Indexed procedure.  NAME <nName> is applied to the
:setName() method of the menu object to be retrieved later.

  Example:

  bRunProc := {|nItem,nIndex,oXbp,nName|nName := oXbp:setName(), ;
                RunProcedure( nName + nItem )}

  DCSUBMENU oMenu1 NAME 1000 ACTIVATEITEM bRunProc
  DCMENUITEM 'Item 1' PARENT oMenu1
  DCMENUITEM 'Item 2' PARENT oMenu1

  DCSUBMENU oMenu1 NAME 2000 ACTIVATEITEM bRunProc
  DCMENUITEM 'Item 1' PARENT oMenu2
  DCMENUITEM 'Item 2' PARENT oMenu2

PARENT <oParent> is the name of the variable that was
assigned to the parent MenuBar (XbpMenuBar()), SubMenu (XbpMenu()),
or TreeViewItem (XbpTreeViewItem()) for this SubMenu.
If this argument is not passed then the parent will be the
object set with the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

INDEX <nIndex> is a variable name to store the index number
that is assigned to this item when it is created.

CHECKED will cause a check mark to appear next to the menu
item.  This option is ignored if a <nAttr> parameter is used.

CHECKWHEN <bWhen> is a code block that is evaluated in the event
loop. This code block must return a logical value.  If the value
returned is .FALSE. then the item will be unchecked. If the
value returned is .TRUE. then the item will be checked. The
parent DCSUBMENU object is passed as a parameter to the code
block.

SEPARATOR is used only if this is a menu separator bar rather
than a selectable item.  Do not include a PROMPT.  All other
parameters are ignored.  This option is ignored if a <nStyle>
parameter is used.

STYLE <nStyle> is a list of XBPMENUBAR_MIS_* numbers defined
in XBP.CH.  These options are summed together.

ATTRIBUTE <nAttr> is a list of XBPMENUBAR_MIA_* numbers defined
in XBP.CH.  These options are summed together.

MESSAGE <cMsg> is the message you want to display in the
message area of the dialogue screen defined by an @..DCMESSAGE
command.  The message is displayed when the mouse is passed over
the menu item.  Optionally, INTO <oMsgBox> will designate which
message box to display the message into. If the INTO clause is
not used, then the last message box in the GetList is the
default.  <oMsgBox> may also be any object that supports the
:setCaption() method.  <bcMsg> may be a code block that returns
a character value.<oSubMenu> is the variable name to assign to
this submenu for storage of the XbpMenu() object.

HELPCODE <cHelp> is a character string that is passed to the
DC_HelpF1() function if F1 is pressed when the mouse is placed
over the menu item.  The help code is used by the Help system
to for specific context-help.

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the Button object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the submenu will be disabled and grayed.
If the value returned is .TRUE. then the submenu will be enabled.
The object is passed as a parameter to the code block.

ID <cID> is a unique 8-character ID to assign to this menu
item.  This is used to allow users to assign a menu item as
"default" by pressing a special key.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TITLE <cTitle> is the title or description of the submenu.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

MESSAGE <bcMsg> is the message you want to display in the
message area of the dialogue screen defined by the DCMESSAGEBOX
command when the mouse is passed over the menu item.  Optionally,
INTO <oMsgBox> will designate which message box to display the
message into. If the INTO clause is not used, then the last
message box in the GetList is the default.  <oMsgBox> may also
be any object that supports the :setCaption() method.  <bcMsg>
may be a code block that returns a character value.

LOCK <cLock> is a lock code to assign to this sub-menu. Lock
codes are any character string up to 5 characters in length.
To gain access to a menu item, a logged on user must own a key
of the same name as the lock or a master key to the lock.  The
function DC_ReadGuiMenuAccess() must be called prior to calling
DC_ReadGui() or using any DCREAD GUI command in which the Getlist
contains menu items with locks.  DC_ReadGuiMenuAccess() is passed
a comma-delimited character string containing the set of keys
owned by the logged on user.  In a typical application, this
function should be called immediately after the logon of a new
user and the users predefined keylist passed to the function.

 Example: DC_ReadGuiMenuAccess('ABC,K*,XY*')
 This key list will allow access to any menu items that have
 no locks or to menu items locked with 'ABC', 'K*' or 'XY*'
 To give access to all menu locks assign the key "*****'.

If a submenu is locked and the user does not own a key, the
submenu and all of its menu items will not be displayed in the
menu.

PROTECT <bProtect> is a code block to evaluate which protects
this menu item.  The code block must return a logical value.  If
the value returned is .TRUE. then the menu item will not be
included in the menu.

ACCELKEY <nAccelKey> is a numeric "hot-key" assignment that will
activate the menu item when the hot-key is pressed.  The key
must be a valid key with the prefix xbeK_*.  These keys are
defined in APPEVENT.CH.

OWNERDRAW will cause the menu to be painted with a more
eye-appealling design, including a vertical bar on the left side
of each submenu with a vertically painted caption and user-defined
colors.  This option is available only when using Xbase++ 1.9 or
later.

BARTEXT <cBarText> is the text to paint on the vertical bar when
the OWNERDRAW options is used.

BARFONT <cBarFont> is the font compound name to use for all
text in the vertical bar when the OWNERDRAW option is used.

FGCOLOR <anFGColor> is the foreground color of the pull down
menus when the OWNERDRAW option is used.  This may be a numeric
GRA_CLR_* value or an array of 3 numeric values for RGB.

BGCOLOR <anBGColor> is the background color of the pull down
menus when the OWNERDRAW option is used.  This may be a numeric
GRA_CLR_* value or an array of 3 numeric values for RGB.

BARCOLOR <anBarColorFG>, <anBarColorBG> are the foreground and
background colors of the vertical bar when the OWNERDRAW option
is used.  These may be a numeric GRA_CLR_* value or an array of
3 numeric values for RGB.

Note: If color options are not used, then they are defaulted to
the colors set by the DCMENUBAR or DCSUBMENU parent.  If the parent
is not a DCMENUBAR or a DCSUBMENU then the colors are defaulted
to those established by DC_XbpMenuConfig().

ITEMFONT <cItemFont> is the font of the menu items when using the
OWNERDRAW  feature.

The BEGINMENU <bBeginMenu> code block is evaluated when a user activates a
menu and starts with the menu selection. {| uNIL1, uNIL2, self | ... }

The ENDMENU <bEndMenu> code block is evaluated when a user has selected a
menu item or aborted menu selection. {| uNIL1, uNIL2, self | ... }

The ITEMMARKED <bItemMarked> code block is evaluated when a menu item in a
menu has been highlighted. This can be used to display additional
information associated with a particular menu item, for example.
{| nItemIndex, uNIL, self | ... }

The ITEMSELECTED <bItemSelected> code block is evaluated when a menu item in a
menu has been selected. This occurs after the user clicks the left
mouse button on the menu item, presses the Return key when the
item is highlighted, or presses the shortcut key combination. This
event is only generated if the selected menu item does not contain
a code block. If it does not contain a code block, the callback
code block or method of the menu object is executed. The first
parameter  <nItemIndex> contains the ordinal position of the selected
menu item. {| nItemIndex, uNIL, self | ... }

SUBITEMFONT <cSubItemFont> is the default font for all subitems of this submenu.
This parameter is ignored if not using the OWNERDRAW option.

COLUMNBREAK causes successive menu items to appear in a new
column of the drop-down or popup menu. Look at the sample
program in the .\SAMPLES\MENU directory.

Notes:

The dialog object created by DCSUBMENU is an object of the XbpMenu() class, therefore it can be manipulated with any iVar or method supported by XbpMenu().

Examples:

/*
This example displays a dialogue box with two tab pages
and a menu with 3 submenus:  File, Edit, Util.
*/

#include "dcdialog.ch"
#include "appevent.ch"

PROCEDURE Xtest()

LOCAL GetList := {}, oFileMenu, oMenuBar, oEditMenu, oMemo, oUtilMenu, ;
      cMemo

USE COLLECT

cMemo := COLLECT->memo

@ 0,0 DCMULTILINE cMemo SIZE 70,7 FONT "10.Courier.Bold"

/* ---- Menu ---- */

DCMENUBAR oMenuBar

DCSUBMENU oFileMenu PROMPT "&File" PARENT oMenuBar

DCMENUITEM "&Open a File" PARENT oFileMenu ;
            ACTION {||Msgbox('OpenFile')} ;

DCMENUITEM "&Close File" PARENT oFileMenu ;
            ACTION {||Msgbox('CloseFile')}

DCMENUITEM "&Pack File" PARENT oFileMenu ;
            ACTION {||Msgbox('Packfile')}

DCSUBMENU oEditMenu PROMPT "&Edit" PARENT oMenuBar

DCMENUITEM "&Next Record" PARENT oEditMenu ;
            ACTION {||dbSkip(), ;
                      cMemo := COLLECT->memo,;
                      DC_GetRefresh(GetList)} ;
            ACCELKEY xbeK_ALT_N ;
            WHEN {||!Eof()}

DCMENUITEM "&Previous Record" PARENT oEditMenu ;
            ACTION {||dbSkip(-1), ;
                      cMemo := COLLECT->memo,;
                      DC_GetRefresh(GetList)} ;
            ACCELKEY xbeK_ALT_P ;
            WHEN {||!Bof()}

DCMENUITEM "&Top of File" PARENT oEditMenu ;
            ACTION {||dbGoTop(), ;
                      cMemo := COLLECT->memo,;
                      DC_GetRefresh(GetList)} ;
            ACCELKEY xbeK_ALT_T

DCMENUITEM "&Bottom of File" PARENT oEditMenu ;
            ACTION {||dbGoBottom(), ;
                      cMemo := COLLECT->memo, ;
                      DC_GetRefresh(GetList)} ;
            ACCELKEY xbeK_ALT_B

DCSUBMENU oUtilMenu PROMPT "&Util" PARENT oMenuBar

DCMENUITEM "Copy File" PARENT oUtilMenu ;
            ACTION {||Msgbox('CopyFile')}

DCMENUITEM "Move File" PARENT oUtilMenu ;
            ACTION {||Msgbox('MoveFile')}

DCREAD GUI ;
   TITLE 'Menu Demo' ;
   FIT ;
   ADDBUTTONS

RETURN

Files:

DCDIALOG.CH

See Also:

   DCMENUBAR
   DCMENUITEM
   dc_readguimenuaccess()
   dc_xbpmenuconfig()


DCTABGROUP

A command for creating TABPAGES in HTML

DCTABGROUP is a command for creating HTML tables that emulate GUI tab pages. The class name associated with this command is DC_HtmlTabGroup(). The :writeHtml() method returns the source code of the table tag and all of its child elements.

Syntax:

@ [ <nRow>, <nCol> ] DCTABGROUP     ;
      [OBJECT <oObject>]            ;
      [TABOBJECT <oTabs>]           ;
      [BORDER <nBorder>]            ;
      [TABS,COLS,COLUMNS <nCols>]   ;
      [CAPTIONS <aCaptions>]        ;
      [NAME <cName>]                ;
      [SELECT <nTabSelect>]         ;
      [ALIGN <nAlign>]              ;
      [PARENT <oParent>]            ;
      [PARENTID <cPID>]             ;
      [BGCOLOR <ncBgC>]             ;
      [SELECTEDCOLOR <xSelColor>]    ;
      [UNSELECTEDCOLOR <xUnSelColor>];
      [BORDERCOLOR <xBorderColor>]    ;
      [BORDERCOLORLIGHT <xBorderColorLight] ;
      [BORDERCOLORDARK <xBorderColorDark>] ;
      [CELLPADDING <nCellPadding>]  ;
      [CELLSPACING <nCellSpacing>]  ;
      [HSPACE <nHspace>]            ;
      [VALIGN <nValign>]            ;
      [VSPACE <nVspace>]            ;
      [WIDTH <nWidth>]              ;
      [CARGO <xCargo>]              ;
      [HIDE <bHide>]                ;
      [EVAL <bEval>]                ;
      [TITLE <cTitle>]              ;
      [PRE,PRETEXT <bcPreHTML>]     ;
      [POST,POSTTEXT <bcPostHTML>]  ;
      [ID <cId>]                    ;
      [GROUP <cGroup>]              ;

Arguments:

<nRow> and <nCol> are the row number and column number of
the table if the parent of this object is a DCTABLE. The
text will be inserted in the cell of the table defined by
the row/column.

OBJECT <oObject> is the name of the variable to assign as a
storage place for this object.

TABOBJECT <oTabs> is the name of the variable to assign as a
storage place for the tab object.

PARENT <oParent> is the name of the variable that was
assigned to the parent of this table. If this argument
is not passed then the parent will be the object set with
the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

BORDER <nBorder> specifies the width in pixels of the border
around the table.

NAME <cName> is the name to assign to this Tab Group.

TABS <nTabs> is the number of tabs in the Tab Group.

SELECT <nTabSelect> is the number of the currently selected tab.

CAPTIONS <aCaptions> is an array of character strings to use
as captions for each tab.  If this array is not used, then
tabs captions, images, etc must be added to the childlist
of the TABOBJECT <oTabs>.

UNSELECTEDCOLOR <xSelColor> is the color of the tabs that are
not selected.  The color may be an RGB color value (#XXXXXX) ,
a standard color name, an RGB 3-element array or a numeric
value defined in GRA.CH.

SELECTEDCOLOR <xUnSelColor> is the color of the tab that is
currently selected.  The color may be an RGB color value
(#XXXXXX), a standard color name, an RGB 3-element array or
a numeric value defined in GRA.CH.

Internet explorer lets you alter the colors that make up an
individual cell's border - if border are turned on with the
border attribute.  The values for BORDERCOLOR <xBorderColor>,
BORDERCOLORDARK <xBorderColorDark> and
BORDERCOLORLIGHT <xBorderColorLight> may be an RGB color
value (#XXXXXX) , a standard color name, an RGB 3-element
array or a numeric value defined in GRA.CH.  The different
colors shade the edges of the border to give it a 3D
appearance with <nBorderColor> shades the central body of
the border.

HSPACE <nHSpace> is the number of pixels of space on the
outside of the table on both the left and right side.

VSPACE <nVSpace> is the number of pixels of space on the
outside of the table on both the top and bottom.

WIDTH <cWidth> is a character string defining the width of
the table.  Values may be either an integer--interpreted
as a number of pixels--or a character string defining a
percentage of the horizontal or vertical space.   The
value 50% means half the available space while 50 means
50 pixels.

CELLPADDING <nCellPadding> defines the amount of space within table
cells (i.e., between the border and cell contents). The
value may be given as a number of pixels or as a percentage,
though most browsers do not support percentages, treating
"20%" as if it were "20". A percentage value is relative to
the vertical space available for vertical padding or spacing,
and the amount is split evenly between the top and bottom.
Horizontal padding and spacing behave similarly.  The padding
or spacing is always applied to all four sides.

CELLSPACING <nCellSpacing> defines the amount of space between
table cells.

Internet explorer lets you alter the colors that make up an
individual cell's border - if border are turned on with the
border attribute.  The values for BORDERCOLOR <xBorderColor>,
BORDERCOLORDARK <xBorderColorDark> and BORDERCOLORLIGHT
<xBorderColorLight> may be an RGB color value (#XXXXXX) ,
a standard color name, an RGB 3-element array or a numeric
value defined in GRA.CH.  The different colors shade the
edges of the border to give it a 3D appearance with
<nBorderColor> shades the central body of the border.

BORDER <nBorder> specifies the width in pixels of the border
around the table.

ALIGN <nAlign> specifies the default horizontal alignment of
items in the table cells.  Possible values are left, right,
and center.

VALIGN <nVAlign> specifies the default vertical alignment of
items in the table cells.  Possible values are top, bottom,
and center.

BGCOLOR <xBGColor> specifies the default background color for
the entire table.  Value may be an RGB color value (#XXXXXX),
a standard color name, an RGB 3-element array or a numeric
value defined in GRA.CH.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container of object created by this definition.

PRE,PRETEXT <bcPreHTML> is a character string or a code block
that returns a character string containing any HTML text
that will precede the opening <table> tag in the source
that is written.

POST,POSTTEXT <bcPostHTML> is a character string or a code block
that returns a character string containing any HTML text
that will follow the closing </table> tag in the source
that is written.

HIDE <bHide> is a code block that is evaluated at the
time the :writeHtml() method is called for the class that
supports this command.  If the code block returns a .TRUE.,
then no HTML code will be written.

EVAL <bEval> is a code block that is evaluated after the
object is created in DC_ReadHtml().  A pointer to the
object associated with this command is passed as an
argument to the code block.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETOBJECT() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not used in the HTML output but is simply a description of the
get object which is saved in the GetList.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], oForm, cHtml, oTabGroup, oTabs, aTabCaptions, ;
      aMemos[4]

DCFORM OBJECT oForm

DCTABGROUP ;
       WIDTH '400' ;
       OBJECT oTabGroup ;
       TABOBJECT oTabs ;
       PARENT oForm ;
       SELECT 2 ;
       COLOR GRA_CLR_WHITE ;
       SELECTEDCOLOR GRA_CLR_GREEN ;
       UNSELECTEDCOLOR GRA_CLR_PALEGRAY ;
       BORDER 0 ;
       CELLPADDING 0 ;
       CELLSPACING 0 ;
       TABS 4

aTabCaptions := {'Customer','Vendor','History','Misc'}

FOR i := 1 TO Len(aTabCaptions)

  DCSUBMIT ;
    TYPE DCHTML_BUTTONTYPE_SUBMIT ;
    CAPTION aTabCaptions[i] ;
    PARENT oTabs ;
    NAME 'App.Tab'  + Alltrim(Str(i))

  aMemos[i] := 'This is the ' + aTabCaptions[i] + ' Memo'
  @ 0,0 DCMULTILINE aMemos[i] SIZE 60,10 ;
    PARENT oTabGroup

NEXT

DCREAD GUI TO cHtml

MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

DCHTML.CH

See Also:

   DCREAD HTML
   dc_html()
   dc_readhtml()
   dc_htmltabgroup()


DCTABLE

A command for creating a TABLE in HTML

The command DCTABLE creates an HTML TABLE definition and adds the definition to the array named GETLIST which is later processed by the DC_READHTML() function or by the DCREAD HTML command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD HTML creates all the DC_Html*() objects from the GetList array and then invokes the :writeHtml() method of the topmost parent object to generate the HTML code.<br><br> A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all objects referenced by the GetList array to be released. <br><br> Any other HTML element may be inserted into a table by simply addressing the table element with it's row number and column number. See example.<br><br>

Syntax:

@ [ <nRow>, <nCol> ] DCTABLE         ;
      [OBJECT <oTable>               ;
      [BORDER <nBorder>]             ;
      [ROWS <nRows>]                 ;
      [COLS,COLUMNS <nCols>]         ;
      [TRIMROWS]                     ;
      [TRIMCOLS]                     ;
      [FILL <cFill>]                 ;
      [ALIGN <nAlign>]               ;
      [PARENT <oParent>]             ;
      [PARENTID <cPID>]              ;
      [BGCOLOR <xBGColor> ]          ;
      [BORDERCOLOR <xBorderColor>]   ;
      [BORDERCOLORLIGHT <xBorderColorLight>] ;
      [BORDERCOLORDARK <xBorderColorDark>]  ;
      [CELLPADDING <nCellPadding>]   ;
      [CELLSPACING <nCellSpacing>]   ;
      [BACKGROUND <bcBackGroun>]     ;
      [HSPACE <nHspace>]             ;
      [VALIGN <nValign>]             ;
      [VSPACE <nVspace>]             ;
      [WIDTH <cWidth>]               ;
      [CLASS <cClass>]               ;
      [CARGO <xCargo>]               ;
      [PRE,PRETEXT <bcPreHTML>]      ;
      [POST,POSTTEXT <bcPostHTML>]   ;
      [HIDE <bHide>]                 ;
      [EVAL <bEval>]                 ;
      [TITLE <cTitle>]               ;
      [ID <cId>]                     ;
      [GROUP <cGroup>]

Arguments:

<nRow> and <nCol> are the row number and column number of
the table if the parent of this object is a DCTABLE. The
text will be inserted in the cell of the table defined by
the row/column.

OBJECT <oTable> is the name of the variable to assign as a
storage place for this object.

PARENT <oParent> is the name of the variable that was
assigned to the parent of this table. If this argument
is not passed then the parent will be the object set with
the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

TRIMCOLS will suppress writing <td></td> column tags
that are empty when at the end of columns.

TRIMROWS will suppress writing <tr></tr> column tags that
are empty when at the end of rows.

ROWS <nRows> is the number of rows in the table.

COLS,COLUMNS <nCols> is the number of columns in the table.

HSPACE <nHSpace> is the number of pixels of space on the
outside of the table on both the left and right side.

VSPACE <nVSpace> is the number of pixels of space on the
outside of the table on both the top and bottom.

FILL <cFill> is a character string to put into each table
cell.  Any writing to the cells will be appended to the
fill string.

WIDTH <cWidth> is a character string defining the width of
the table.  Values may be either an integer--interpreted
as a number of pixels--or a character string defining a
percentage of the horizontal or vertical space.   The
value 50% means half the available space while 50 means
50 pixels.

CELLPADDING <nCellPadding> defines the amount of space within table
cells (i.e., between the border and cell contents). The
value may be given as a number of pixels or as a percentage,
though most browsers do not support percentages, treating
"20%" as if it were "20". A percentage value is relative to
the vertical space available for vertical padding or spacing,
and the amount is split evenly between the top and bottom.
Horizontal padding and spacing behave similarly.  The padding
or spacing is always applied to all four sides.

CELLSPACING <nCellSpacing> defines the amount of space between
table cells.

Internet explorer lets you alter the colors that make up an
individual cell's border - if border are turned on with the
border attribute.  The values for BORDERCOLOR <xBorderColor>,
BORDERCOLORDARK <xBorderColorDark> and
BORDERCOLORLIGHT <xBorderColorLight> may be an RGB color
value (#XXXXXX) , a standard color name, an RGB 3-element
array or a numeric value defined in GRA.CH.  The different
colors shade the edges of the border to give it a 3D
appearance with <nBorderColor> shades the central body of
the border.

BACKGROUND <bcBackGround> is the name of a .JPG file to use as
the background of the table.  If <bcBackGround> is a code block
it must return a character string.  The image will be tiled over
the entire area of the table.

BORDER <nBorder> specifies the width in pixels of the border
around the table.

ALIGN <nAlign> specifies the default horizontal alignment of
items in the table cells.  Possible values are left, right,
and center.

VALIGN <nVAlign> specifies the default vertical alignment of
items in the table cells.  Possible values are top, bottom,
and center.

BGCOLOR <xBGColor> specifies the default background color for
the entire table.  Value may be an RGB color value (#XXXXXX),
a standard color name, an RGB 3-element array or a numeric
value defined in GRA.CH.

HEADERS <aHeaders> is an array of character strings
containing the headers for each column in the table.  The
length of the array should be equivalent to the number of
columns.

FOOTERS <aFooters> is an array of character strings
containing the footers for each column in the table.  The
length of the array should be equivalent to the number of
columns.

CLASS <cClass> sets a class name for the table. The class name
is case sensitive.  A class is used with style sheets to
give the table a pre-defined appearance.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container of object created by this definition.

PRE,PRETEXT <bcPreHTML> is a character string or a code block
that returns a character string containing any HTML text
that will precede the opening <table> tag in the source
that is written.

POST,POSTTEXT <bcPostHTML> is a character string or a code block
that returns a character string containing any HTML text
that will follow the closing </table> tag in the source
that is written.

HIDE <bHide> is a code block that is evaluated at the
time the :writeHtml() method is called for the class that
supports this command.  If the code block returns a .TRUE.,
then no HTML code will be written.

EVAL <bEval> is a code block that is evaluated after the
object is created in DC_ReadHtml().  A pointer to the
object associated with this command is passed as an
argument to the code block.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETOBJECT() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not used in the HTML output but is simply a description of the
get object which is saved in the GetList.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group.

Notes:

DCTABLE uses the DC_HtmlTable() class to create the tableobject and write the HTML source.

Examples:

/*
This example will build a table with 4 sub-tables.
*/

FUNCTION Xtest()

LOCAL i, j, GetList[0], cHtml, oTable, nTable, aSubTables[2,2]

DCTABLE OBJECT oTable1 ;
     ROWS 2 ;
     COLUMNS 2 ;
     BORDER 5 ;
     BORDERCOLOR '#336677' ;
     TRIMROWS ;
     TRIMCOLS ;
     BGCOLOR '#339977'

nTable := 1
FOR i := 1 TO 2
  FOR j := 1 TO 2
    @ i,j DCTABLE ;
      OBJECT aSubTables[i,j] ;
      BGCOLOR '#33AA77' ;
      ROWS 4 ;
      COLUMNS 4 ;
      FILL Alltrim(Str(i)) + '/' + Alltrim(Str(j)) ;
      PARENT oTable1
    @ 1,1 DCSAY '<h1>' + Alltrim(Str(nTable++)) + ;
                '</h1>' PARENT aSubTables[i,j]
  NEXT
NEXT

DCREAD HTML TO cHtml
MemoWrit('TEST.HTM',cHtml)

RETURN nil

Files:

DCHTML.CH

See Also:

   DCREAD HTML
   dc_html()
   dc_readhtml()
   dc_htmltable()


DCTREEITEM

Create a new item for a Tree View

The command DCTREEITEM creates a new TreeView item and adds the object to the array named GETLIST which is later processed by the DC_READGUI() function or by the DCREAD GUI command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD GUI activates the edit mode for all objects found in the GetList array. A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all Get objects referenced by the GetList array to be released. <br><br> DCTREEITEM is used with the @ DCTREEROOT command to create a TreeView system for viewing any kind of data.

Syntax:

 DCTREEITEM                                                       ;
   [CAPTION <cCaption>] ;
   [PARENT <oParent>] ;
   [LOCK <cLock>] ;
   [PROTECT <bProtect>] ;
   [ACTION <bAction>] ;
   [HELPCODE <cHelpCode>] ;
   [MESSAGE <cMsg> [INTO <oMsg>]] ;
   [CARGO <xCargo>] ;
   [ID <cId>] ;
   [OBJECT <oObject>] ;
   [TITLE <cTitle>] ;
   [PREEVAL <bPreEval>] ;
   [EVAL <bEval>] ;
   [GROUP <cGroup>] ;
   [IMAGEEXPANDED <noImageExpanded>] ;
   [IMAGENORMAL <noImageNormal>] ;
   [IMAGEMARKED <noImageMarked>] ;
   [IMAGECHECKED <noImageChecked>] ;
   [CHECKWHEN <bCheckWhen>] ;
   [CHARCHECKED <cCharChecked>] ;
   [SUBCLASS <cSubClass>]

Arguments:

CAPTION <cCaption> is the Caption which will appear in the
Tree View window for this item.

PARENT <oParent> is the name of the variable that was assigned to
the parent XbpTreeView or DCTREEROOT object for this object.
If this argument is not passed then the parent will be the
object set with the DCSETPARENT command.

OBJECT <oObject> is the variable to use as a container for the
object after it is created by the GUI reader.

MESSAGE <bcMsg> is the message you want to display in the
message area of the dialogue screen defined by the DCMESSAGEBOX
command when the item is marked.  Optionally, INTO <oMsgBox>
will designate which message box to display the message into.
If the INTO clause is not used, then the last message box in the
GetList is the default.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the object will be disabled and grayed.
If the value returned is .TRUE. then the object will be enabled.
The object is passed as a parameter to the code block.

ACTION <bAction> is a code block to evaluate when this tree item
is selected either with the ENTER key or a double-click.  The
code block is passed three parameters as follows:

 {| oItem, aRect, oTree | ... }

 <oItem> is the selected XbpTreeViewItem object.

 <aRect> := { nX1, nY1, nX2, nY2 }

 <aRect> is an array with four elements. They contain the
 xy-coordinates for the lower left and upper right corner of
 <oItem> . The origin for the coordinates is the lower left
 corner of the parent XpbTreeView object.

 <oTree> is the Parent XbpTreeView object.

HELPCODE <cHelp> is a character string that is passed to the
DC_HelpF1() function if F1 is pressed or the HELP button
is clicked when this GET has focus.  This HELPCODE allows
the Help system to override the passing of the Procedure and
Varname for more specific context-help.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

PREEVAL <bPreEval> is a code block to be evaluated by the GUI
reader before the Xbase Parts object is created.  The object is
passed to the code block.

EVAL <bEval> is a code block to be evaluated by the GUI reader
after the Xbase Parts object is created.  The object is passed
to the code block.

IMAGEEXPANDED <noImageExpanded> is the icon or bitmap to use when
this tree item is expanded.  If <noImageExpanded> is a numeric
value it must be an icon resource that is linked to the .EXE or
exists in <cDllName>.  If <noImageExpanded> is an object, it
must be a bitmap of the XbpBitMap() class.  An object may be used
only with Xbase++ 1.7 or later.

IMAGENORMAL <noImageNormal> is the icon resource to use when this
tree item is not marked or expanded.  If <noImageNormal> is a
numeric value it must be an icon resource that is linked to the
.EXE or exists in <cDllName>.  If <noImageNormal> is an object, it
must be a bitmap of the XbpBitMap() class.  An object may be used
only with Xbase++ 1.7 or later.

IMAGEMARKED <noImageMarked> is the icon resource to use when this
tree item is marked.  If <noImageMarked> is a numeric value it
must be an icon resource that is linked to the .EXE or exists in
<cDllName>.  If <noImageMarked> is an object, it must be a bitmap
of the XbpBitMap() class.  An object may be used only with Xbase++
1.7 or later.

IMAGECHECKED <noImageChecked> is the icon resource to use when this
tree item is marked.  If <noImageChecked> is a numeric value it
must be an icon resource that is linked to the .EXE or exists in
<cDllName>.  If <noImageChecked> is an object, it must be a bitmap
of the XbpBitMap() class.  An object may be used only with Xbase++
1.7 or later.  A tree item is checked or unchecked with the
CHECKWHEN codeblock.

CHECKWHEN <bCheckWhen> is a code block that is evaluated every
time DC_GetRefresh() or DC_GetWhen() is called.  This code block
must return a logical value of .T. to cause the item to be
checked or .F. to cause the item to be unchecked.  A checked item
will display a programmer-defined icon (defined by IMAGECHECKED)
and/or sequence of characters at the start of the item caption
(defined by CHARCHECKED).

CHARCHECKED is a character or sequence of characters to display
in the item caption (at the beginning of the caption) when the
item is checked via the CHECKWHEN code block.

DLLNAME <cDllName> is the name of the DLL containing the image
icons.  If this clause is not used, then the icons must be linked
into the .EXE.

LOCK <cLock> is a lock code to assign to this tree item. Lock
codes are any character string up to 5 characters in length.
To gain access to a tree item, a logged on user must own a key
of the same name as the lock or a master key to the lock.  The
function DC_ReadGuiMenuAccess() must be called prior to calling
DC_ReadGui() or using any DCREAD GUI command in which the Getlist
contains tree items with locks.  DC_ReadGuiMenuAccess() is passed
a comma-delimited character string containing the set of keys
owned by the logged on user.  In a typical application, this
function should be called immediately after the logon of a new
user and the users predefined keylist passed to the function.

 Example: DC_ReadGuiMenuAccess('ABC,K*,XY*')
 This key list will allow access to any tree items that have
 no locks or to tree items locked with 'ABC', 'K*' or 'XY*'
 To give access to all tree locks assign the key "*****'.

If a tree item is locked and the user does not own a key, the
item and it's sub-items will not be displayed in the tree.

PROTECT <bProtect> is a code block to evaluate which protects
this tree item.  The code block must return a logical value.  If
the value returned is .TRUE. then the tree item will not be
included in the tree.

SUBCLASS <cSubClass> is a string containing a class name that
will be used to create the class, rather than DC_XbpTreeViewItem().
This class should inherit from DC_XbpTreeViewItem().
See the example in \exp19\samples\subclass.

Notes:

The object created by DCTREEITEM is an object of the XbpTreeViewItem() class, therefore it can be manipulated with any iVar or method supported by XbpTreeViewItem().

Examples:

#include "dctree.ch"

PROCEDURE Xtest()

LOCAL GetList := {}, oTree, oSubTree1, oSubTree2, cSelected

@ 1,1 DCTREEROOT SIZE 30,10 OBJECT oTree CAPTION 'Tree Root' ;
  HASLINES ;
  HASBUTTONS ;
  ITEMSELECTED {|o| cSelected := o:caption, ;
                    DC_ReadGuiEvent(DCGUI_EXIT_OK,GetList)}

DCTREEITEM CAPTION 'SubTree 1' PARENT oTree OBJECT oSubTree1
  DCTREEITEM CAPTION 'Sub-SubTree 1/1' PARENT oSubTree1
  DCTREEITEM CAPTION 'Sub-SubTree 1/2' PARENT oSubTree1
  DCTREEITEM CAPTION 'Sub-SubTree 1/3' PARENT oSubTree1

DCTREEITEM CAPTION 'SubTree 2' PARENT oTree OBJECT oSubTree2
  DCTREEITEM CAPTION 'Sub-SubTree 2/1' PARENT oSubTree2
  DCTREEITEM CAPTION 'Sub-SubTree 2/2' PARENT oSubTree2
  DCTREEITEM CAPTION 'Sub-SubTree 2/3' PARENT oSubTree2

DCREAD GUI FIT ADDBUTTONS

DC_MsgBox({'You Selected:',cSelected})

RETURN nil

Files:

DCTREE.CH

See Also:

   @ DCTREEROOT
   dc_readguimenuaccess()


DCUSEREVENT

Create an action that is tied to a user event

DCUSEREVENT is used to run an action code block when a user event is received. This can be handy for refreshing or updating a window from another thread. See sample program in ..\samples\events.

Syntax:

DCUSEREVENT <nEvent> ACTION <bAction>

Arguments:

<nEvent> is the user event.  It is usually xbeP_User + offset.

<bAction> is the codeblock to evaluate.

Files:

dcdialog.ch, dclipx.dll


DCVARGROUP

Create a group of vars in a dynamically-created class

DCVARGROUP is use to create a group of vars in a dynamically-created class. This is better than using arrays for passing variables. Look at the sample program in .\samples\vars.

Files:

_DCFUNCT.PRG, DCDIALOG.CH, DCLIPX.DLL

See Also:


DCVARS

A command for managing HIDDEN variables in HTML

DCVARS is a command for creating and replicating hidden variables in HTML forms.<br><br>The command DCVARS creates an HTML element definition and adds the definition to the array named GETLIST which is later processed by the DC_READHTML() function or by the DCREAD HTML command. The GETLIST array must be first declared and initialized to the value of {}. The command DCREAD HTML creates all the DC_Html*() objects from the GetList array and then invokes the :writeHtml() method of the topmost parent object to generate the HTML code.<br><br>A Getlist object remains stored as long as it is referenced in an array or by a variable. The commands CLEAR and CLEAR GETS assign an empty array to the GetList variable. This also occurs after the completion of the DCREAD command if it is called without the SAVE option, causing all objects referenced by the GetList array to be released.<br><br>

Syntax:

DCVARS                                 ;
       [OBJECT <oVars>]                ;
       [PARENT <oParent>]              ;
       [PARENTID <cPID>]               ;
       [CARGO <xCargo>]                ;
       [HIDE <bHide>]                  ;
       [INCLUDE <aInclude>]            ;
       [REPLICATE <aVars>]             ;
       [EXCLUDE <aExclude>]            ;
       [PRE,PRETEXT <bcPreText>]       ;
       [POST,POSTTEXT <bcPostText>]    ;
       [EVAL <bEval>]                  ;
       [ID <cId>]                      ;
       [GROUP <cGroup>]                ;

Arguments:

PARENT <oParent> is the name of the variable that was
assigned to the parent of this object. If this argument
is not passed then the parent will be the object set with
the DCSETPARENT command.

PARENTID <cParentID> may be used in lieu of the PARENT <oParent>
clause.  This identifies the ID of the parent instead of the
parent's object variable name.

REPLICATE <aVars> is a 2-dimensional array containing all the
system variables passed in to the application from the
HTTP handler.

INCLUDE <aInclude> is a 2-dimensional array containing any
additional vars.

EXCLUDE <aExclude> is a 1-dimensional array containing the
names of vars in <sysVars> to exclude.  This array may contain
names with * wildcard characters.  Names are case sensitve.

OBJECT <oVars> is the name of the variable to assign as a
storage place for this object.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container of object created by this definition.

PRE,PRETEXT <bcPreHTML> is a character string or a code block
that returns a character string containing any HTML text
that will precede the opening <table> tag in the source
that is written.

POST,POSTTEXT <bcPostHTML> is a character string or a code block
that returns a character string containing any HTML text
that will follow the closing </table> tag in the source
that is written.

HIDE <bHide> is a code block that is evaluated at the
time the :writeHtml() method is called for the class that
supports this command.  If the code block returns a .TRUE.,
then no HTML code will be written.

EVAL <bEval> is a code block that is evaluated after the
object is created in DC_ReadHtml().  A pointer to the
object associated with this command is passed as an
argument to the code block.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETOBJECT() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not used in the HTML output but is simply a description of the
get object which is saved in the GetList.

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group.

Notes:

DCVARS creates an object of the DC_HtmlVars() class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], cHtml, aVars, oForm

aVars := { { 'App.Text.1', 'some text' }, ;
           { 'App.Text.2', 'more text' }, ;
           { 'App.Text.3', 'still more text' }, ;
           { 'App.Checkbox', 'on' }, ;
           { 'App.RadioButton', 'Mint' }, ;
           { 'App.Memo', 'lots of text' }, ;
           { 'App.RecordNumber', '12' }, ;
           { 'App.Database', 'CUSTOMER' }, ;
           { 'App.Account', '40055' } }

DCFORM OBJECT oForm

DCVARS ;
   PARENT oForm ;
   REPLICATE aVars ;
   EXCLUDE { 'App.Text.*','App.Memo' } ;
   INCLUDE { { 'App.Date', Date() }, ;
             { 'App.Time', Time() } }

DCREAD HTML TO cHtml
MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

DCHTML.CH

See Also:

   DCREAD HTML
   dc_html()
   dc_readhtml()
   dc_htmlvars()


ECHO_PPO

Display the pre-processed output of a DOT PROMPT command

The => command is used to display the pre-processed output of commands entered at the dot prompt.

Syntax:

 => <command>

Arguments:

<command> is the command string to translate.

Examples:

 . => STACK
DC_CallStack()

 . => CLOSE
dbCloseArea()

 . => ? K_ESC
Qout( 27 )

See Also:

   dc_dot()


GETSETFUNCTION

Create a Get/Set Function

GETSETFUNCTION is a command that is used to create a Get/Set function for Getting or Setting a value.

Syntax:

GETSETFUNCTION <cFuncName> DEFAULT <xDefault>

Arguments:

<cFuncName> is the name of the function to create.

<xDefault> is the default value to return.

Notes:

The value stored is visible in all threads, therefore a valuecan be set in one thread and then read in another thread.

Use GETSETTHREADFUNCTION for a thread-safe Get/Set function.

Examples:

GETSETFUNCTION MyTest DEFAULT 0

* -------------

? MyTest()

0

MyTest(12)
? MyTest()

12

Files:

DCDIALOG.CH

See Also:

   GETSETTHREADFUNCTION


GETSETTHREADFUNCTION

Create a Get/Set Function that is thread-safe

GETTHREADSETFUNCTION is a command that is used to create a Get/Set function for Getting or Setting a value.<br><br>The value being stored or retrieved is thread-safe.<br><br>

Syntax:

GETSETTHREADFUNCTION <cFuncName> DEFAULT <xDefault>

Arguments:

<cFuncName> is the name of the function to create.

<xDefault> is the default value to return.

Notes:

The value retrieved is visible only in the thread in which it wasset, therefore call to the function in one thread will notaffect another thread.

Use GETSETFUNCTION for a global (non-safe) Get/Set function.

Examples:

GETSETTHREADFUNCTION MyTest DEFAULT 0

* -------------

? MyTest()

0

MyTest(12)
? MyTest()

12

Files:

DCDIALOG.CH

See Also:

   GETSETFUNCTION


GUI

Set the Dialogue mode to GUI or TEXT

GUI or DCGUI is used to set Text or Gui mode for Dual-Mode Functions. The eXPress++ library contains a variety of functions which operate in "Dual-Mode". When GUI mode is ON, the function uses a GUI dialogue based on Xbase Parts. When the GUI mode is OFF the function works in standard text-mode.<br><br>

Syntax:

GUI ON | OFF

Returns:

 .TRUE. if any gets were updated, .FALSE. otherwise.

Arguments:

GUI ON will cause eXPress++ to process Dual-Mode functions as
a GUI dialogue.  GUI OFF will cause eXPress++ to process all
Dual-Mode functions as a TEXT dialogue.

Examples:

  /*
  In this example, DC_ReadBox() and DC_Impl() will only
  display and restore the window in Text-Mode.  They are
  ignored in GUI mode.
  */

  #include "dcdialog.ch"

  PROCEDURE Xtest( )

  LOCAL GetList := {}, GetOptions, aReadArea, cLastName := Space(15), ;
        cFirstName := Space(15), cCompany := Space(25), ;
        cStreet := Space(25), cCity := Space(25), cState := Space(2), ;
        cCountry := Space(25), cPhone := Space(15), cScrn, lOk

  lGui := IIF( Valtype(lGui)='L',lGui,.t.)

  GUI ON   //  set GUI mode

  cScrn := DC_ReadBox(3,5,15,75,,@aReadArea)

  @ 5,10 DCSAY ' Last Name' GET cLastName
  @ 5,40 DCSAY 'First Name' GET cFirstName
  @ 7,10 DCSAY '   Company' GET cCompany
  @ 8,10 DCSAY '    Street' GET cStreet
  @ 9,10 DCSAY '      City' GET cCity
  @10,10 DCSAY '     State' GET cState
  @11,10 DCSAY '   Country' GET cCountry
  @13,10 DCSAY '     Phone' GET cPhone PICT '(999)-999-9999'

  DCGETOPTIONS SAYWIDTH 70 SAYRIGHTJUST

  lOk := DC_ReadGets( GetList,"Enter Data",aReadArea,;
                      GetOptions )
  DC_Impl(cScrn)

  RETURN

Files:

DCDIALOG.CH

See Also:

   dc_readmodal()
   dc_readgui()
   dc_gui()


LOG

Write system status to a log file

LOG will log information about the currently running procedure to a log file including the current status of work areas and environment variables.<br><br> A dialog window will be displayed first for the user to type in specific information that will be saved in the log file or to specify the name and location of the log file.<br><br>

Syntax:

 LOG [TO <cFileName>]

Arguments:

TO <cFileName> is the name of the file to write.

Examples:

 . LOG

Files:

_DCLOG.PRG, DCLIP2.DLL

See Also:

   dc_log()
   dc_setdclip()


SAVE ARRAY

Save a multidimensional array to a binary file

SAVE ARRAY will save the contents of any multi-dimensional array to a binary file for later restoring with RESTORE ARRAY.<br><br>

Syntax:

 SAVE ARRAY <aArray> ;
    [TO <cFileName>]

Arguments:

<aArray> is any multidimensional array.

TO <cFileName> is the name of the binary file to create with
the array contents.  If this argument is not passed then the
file will be assigned the name <aArray>.DCA.

Examples:

 . aDir := Directory()
 . SAVE ARRAY aDir
 . SAVE ARRAY aDir TO junk.ar

Files:

_DCASAVE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_asave()


WTF

Send debug information to a browse-style debugging window

DCBDEBUG or DD is used to send data to a browse-style debugging window when debugging GUI applications. <br><br> A list of expressions may be included and the output of each expression will be displayed in a new row in the browse window.<br><br> This is a major improvement over DCQDEBUG because it uses an array browse rather than a memo to show debug information. Improvements: a. Updating the window is much faster therefore does not slow down application.<br><br> b. Data is in resizeable and moveable columns<br><br> c. Each debug line may have its own color.<br><br> d. Supports multiple windows.<br><br> e. Double-Clicking on debug item in window displays more info about that item, such as array browsing, object inspecting, etc.<br><br> f. Information doesn't scroll off the window. No limit to amount of debugging information.<br><br> g. Double-clicking the heading of a column will optimize the width of that column to display all data.<br><br> h. Double-clicking the data area of a column will cause the editor to go to the associated line of code in the source file. <br><br> <br><br>

Syntax:

 DCBDEBUG <xExpr1> [ ; <xExprN> ] ;
          [WINDOW <nWindow>] ;
          [COLOR <nbFgColor> [,<nBgColor>] ;
          [PAUSE <bPause>] ;
          [PAUSE] ;
          [ALWAYSONTOP] ;
          [WHEN <bWhen>]

Arguments:

<xExpr1> through <xExprN> is any expression.

WINDOW <nWindow> is the debug window to send the information.
If this clause is not used then the information is sent to debug
window # 1.

COLOR <nbFgColor> and <nBgColor> are the foreground and background
colors of the information to display in the window.  If <nbFgColor>
is a code block, then <nBgColor> is ignored.  The code block must
return an array of two numeric elements, ie a foreground color
and a background color.

PAUSE will cause the program execution to stop until the "Continue"
button on the debug window is activated.

PAUSE <bPause> will cause the program execution to stop only if
<bPause> evaluates as .TRUE.

ALWAYSONTOP will force the debug window to always display in
front of all other windows.

WHEN <bWhen> is a codeblock that will cause the debug info to be
displayed only when the codeblock returns .t.
Ex: DCBDEBUG i, oInfo WHEN {||i==16}

Notes:

A shortened command: DD Use this as a replacement for DCBDEBUG.

DC_DebugQoutAppendBlock() is a get-set function used to setupadditional information to append to each debug line.

Examples:

 #include "dcdialog.ch"

 USE COLLECT NEW SHARED

 DCBDEBUG Alias(), RecCount()
 DCBDEBUG RecNo() WINDOW 2 COLOR GRA_CLR_RED

Files:

DCDIALOG.CH

See Also:

   dc_debugbrowse()
   DCQDEBUG
   DCLDEBUG
   dc_wtfenable()


USER-DEFINED COMMANDS

Create a User-Defined object for displaying with GUI reader

User-Defined Commands are similar to the @ DCCUSTOM command with the exception that the programmer can create his/her own syntax for the command. The Syntax and Arguments listed below are a "suggestion" only. The only requirement is that the command arguments are properly parsed into the GetList array. This is accomplished by creating a custom command similar to the "template" provided in DCUDC.CH.<br><br> A User-Defined command must add a GetList item of the type GETLIST_USER (defined in DCDIALOG.CH) plus any numeric offset from 0 to 1000. This allows for up to 1000 user-defined commands in an application.

Syntax:

@ <nRow>,<nCol> MYCOMMAND <bCustom> ;
    [SIZE <nWidth> [,<nHeight>]] ;
    [VAR <uVar>] ;
    [PARENT <oParent>] ;
    [CAPTION <cCaption>] ;
    [PRESENTATION <aPres>] ;
    [TYPE <nType>] ;
    [OBJECT <oCustom>] ;
    [COLOR <ncFgC> [,<ncBgC>] ] ;
    [OPTIONS <aOptions>] ;
    [DATALINK <bLink>] ;
    [FONT <cFont>] ;
    [MESSAGE <cMsg> [INTO <oMsgBox>]] ;
    [HIDE <bHide>] ;
    [WHEN <bWhen>] ;
    [EDITPROTECT <bProtect>] ;
    [VALID <bValid>] ;
    [HELPCODE <cHelpCode>] ;
    [TOOLTIP <cToolTip>] ;
    [ACTION <bAction>] ;
    [CURSOR <nCursor>] ;
    [CARGO <xCargo>] ;
    [EVAL <bEval] ;
    [PIXEL] ;
    [RELATIVE <oRel>] ;
    [ID <cId>] ;
    [TITLE <cTitle>] ;
    [ACCELKEY <nKey>] ;
    [GOTFOCUS <bGotFocus>] ;
    [LOSTFOCUS <bLostFocus>] ;
    [TABSTOP] ;
    [NOTABSTOP] ;
    [TABGROUP <nTabGroup>] ;
    [VISIBLE] ;
    [INVISIBLE] ;
    [GROUP <cGroup>]

Arguments:

<nRow>, <nCol> are the coordinates on the screen.
Coordinates are always relative to position 0,0 ie. Top,Left
of the parent object, unless the RELATIVE <oRel> argument is
used.  If no parent is assigned, then the parent is the Dialog
box.  IF the PIXEL option is set to .TRUE. in DCGETOPTIONS,
then the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel mode by
including PIXEL as a command argument.
<nRow> is stored in element nGETLIST_STARTROW.
<nCol> is stored in element nGETLIST_STARTCOL.

<bCustom> is a required code block.  This is the code block
that is evaluated to create the custom object.  It requires
the following form:

 { | <a> | <MyFunc>( <a> ) }

 <a> is an array of information that is passed to the custom
 function.

 Element  Type Description
 -------  ---- ------------------------------------------------

   [1]     A   The GetList array

   [2]     N   The GetList pointer (the element containing this
               object).

   [3]     O   The Parent object

   [4]     A   A two element array containing the start column
               and start row.  The values will be converted to
               pixel coordinates.

   [5]     A   A two element array containing the width and
               height of the object.  The values will be
               converted to pixels.

   [6]     A   Optional Presentation Parameters

   [7]     L   A .TRUE. if the object is VISIBLE.

RELATIVE <oRel> is an optional object in the Getlist which
determines the start coordinates of this object.  If this
option is used, then the <nSrow>, <nSCol> coordinates are
relative to the starting coordinates of <oRel> rather than
the parent object.

SIZE <nWidth>, <nHeight> defines the size of the object.
IF the PIXEL option is set to .TRUE. in DCGETOPTIONS, then
the numbers are in pixels otherwise they are in standard
text-based coordinates.  You can also force the pixel mode by
including PIXEL in the command.
<nWidth> is stored in element nGETLIST_WIDTH
<nHeight> is stored in element nGETLIST_HEIGHT

VAR <uVar> is an optional memory variable that is used with
this object.  It is converted to a code block using the
function DC_GetAnchorCB() and stored in element bGETLIST_VAR.
This code block is usually attached to the :dataLink instance
var of an Xbase Parts object.

PARENT <oParent> is the name of the variable that was assigned to
the parent object for this object.  Only use this clause if you
are placing this object onto another dialogue object.  If this
clause is not used, then the object will be displayed in the
top-level dialogue screen. This is converted to a code-block by
the function DC_GetAnchorCB() and is stored in element
oGETLIST_PARENT.

<oGroup> is the name of the variable to assign as a storage
place for this object.  It is converted to a code-block by
the function DC_GetAnchorCB() and is stored in element
oGETLIST_GROUP.

CAPTION <cCaption> is the caption to use with the object
and is stored in element cGETLIST_CAPTION.

PRESENTATION <aPres> is a two-dimensional array. If specified,
this contains presentation parameters for the object.
The first column of the array must contain #define constants
from the XBP.CH file starting with the prefix XBP_PP_. These
constants define the presentation parameters that can be set
for the object and include colors and fonts. The second column
of the array in <aPres> contains the value for each setting.
These are also generally set using #define constants from the
GRA.CH file.  The array is stored in element
aGETLIST_PRESENTATION.

TYPE <nType> defines the "type" of the object and is stored
in element nGETLIST_TYPE.

OBJECT <oObject> is a local variable to store a reference to
this object.  It is converted to a code-block by the function
DC_GetAnchorCB() and is stored in element oGETLIST_OBJECT.

COLOR <cColor> is a text-based color string for the object
that is stored in element cGETLIST_COLOR.

OPTIONS <xOptions> can be any type of variable.  It is stored
in element xGETLIST_OPTIONS.

DATALINK is an optional code block that is attached to the
<uVar> via the function DC_GetAnchorCB().  This code block is
evaluated when the :dataLink var is evaluated by an Xbase
Parts object.

FONT <cFont> is a font to use with this object and is stored
in element cGETLIST_FONT.

MESSAGE <cMsg> is the message you want to display in the
message area of the dialogue screen defined by the DCMESSAGEBOX
command when the object is in focus.  Optionally, INTO <oMsgBox>
will designate which message box to display the message into.
If the INTO clause is not used, then the last message box in the
GetList is the default.

PICTURE <cPict> is a character string specifying formatting
options for the value of <uVar> during display and editing.
It is stored in element cGETLIST_PICTURE.

WHEN <bWhen> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .FALSE. then the object will be disabled and grayed.
If the value returned is .TRUE. then the object will be enabled.
The code block is stored in element bGETLIST_WHEN.

HIDE <bHide> is a code block that is evaluated in the event loop.
This code block must return a logical value.  If the value
returned is .TRUE. then the object will be hidden from view.  If
the value returned is .FALSE. then the object will be displayed.

EDITPROTECT <bProtect> is an optional condition tested during the
execution of the GUI gets by the DCREAD GUI command, before the
object receives input focus (before it is activated). When the
condition returns the value .T. (true), the object receives the
input focus.  Otherwise, it is skipped. <bProtect> is a code
block that must return a logical value when evaluated. The object
is passed to the code block prior to the object receiving input
focus. This clause behaves similar to the WHEN clause with the
exception that the object is not disabled (grayed out).  The
code block is stored in bGETLIST_PROTECT.

VALID <bValid> is an optional condition tested during the
navigation through the dialog objects when an object loses
focus (before it is deactivated).  If the condition returns the
value .T. (true), the object loses the input focus, otherwise,
it remains active. <bValid> is a code block that must return a
logical value when it is evaluated.  The object is passed to the
code block prior to the object losing input focus.  The
code block is stored in element bGETLIST_VALID.

HELPCODE <cHelp> is a character string that is passed to the
DC_HelpF1() function if F1 is pressed or the HELP button
is clicked when this object has focus.  This HELPCODE allows
the Help system to override the passing of the Procedure and
Varname for more specific context-help.  The help code is
stored in element cGETLIST_HELPCODE.

TOOLTIP <cToolTip> is a character string which will display
as a "Tool Tip" next to the object when the cursor is passed
over the object.  The tooltip is stored in element
cGETLIST_TOOLTIP.

CURSOR <nCursor> is an optional mouse pointer to use for this
object.  System mouse pointers start with XBPWINDOW_POINTERTYPE_
and are defined in XPB.CH.  The default pointer is
XBPWINDOW_POINTERTYPE_POINTER.  <nCursor> may also be a resource
ID that points to a Bit-Map that has been compiled with the
resource compiler and linked to the .EXE.  The cursor is stored
in element nGETLIST_CURSOR.

CARGO <xCargo> is any kind of data you wish to to add to the
:cargo container for this object.  The cargo may be accessed
at any time via the :cargo exported variable, however it will not
be stored in the same manner it is entered.  The :cargo container
of DCDIALOG objects is an array of at least three elements:

 [1] - A numeric value that is a pointer to the Getlist array
       for this object.

 [2] - A pointer to the GetList array.

 [3] - The value of <xCargo>.

 [4] and up - optional values added by the GUI reader.

<xCargo> is stored in element xGETLIST_CARGO.

ACTION <bAction> is a code-block to be used with objects
that execute an action, like push-buttons.  This code block
is stored in element bGETLIST_ACTION.

COLOR <ncFGc>, <ncBGc> are foreground and background colors.
They may be character strings representing valid text-based
colors supported by SetColor() or they may be numeric constants
which begin with either the prefix GRA_CLR_ or the prefix
XBPSYSCLR_ as defined in GRA.CH or XBP.CH.

ID <cId> is a unique identifier for this object.  This ID is used
with functions like DC_GETORIGUPDATED() to determine the status
of a get object.

TITLE <cTitle> is a title to assign to this object.  The title
is not displayed on the screen but is simply a description of the
get object which is saved in the GetList.

ACCELKEY <nKey> is a numeric "hot-key" assignment that will set
focus to the custom object when the hot-key is pressed.  The key
must be a valid key with the prefix xbeK_*.  These keys are
defined in APPEVENT.CH.

GOTFOCUS <bGotFocus> is a code block that is evaluated when this
object receives input focus.

LOSTFOCUS <bLostFocus> is a code block that is evaluated when this
object loses input focus.

TABSTOP will cause the object (Xbase Part) to be set when using
the Tab key.  Note: When logical groups are defined in a dialog
using TABGROUP <nTabGroup>, TABSTOP is usually set to .T. (true)
for the first dialog element in the group.  This allows the first
dialog element of a group to be activated using the Tab key.

NOTABSTOP will cause the object (Xbase Part) to be ignored when
using the Tab key. This clause is needed only to override any
default setting of TabStop by the DCGETOPTIONS [TABSTOP] command.

TABGROUP <nTabGroup> allows objects (Xbase Parts) that are created
immediately after one another in the GetList to be combined into
logical groups. This allows the user to navigate within a dialog
from group to group by pressing the Tab key.  Within a group of
dialog elements navigation is performed using the cursor keys.

Only constants defined in the XBP.CH file can be used as values
for this instance variable.  The following table lists the
available constants:

#define constants for <nTabGroup>:

 Constant             Description

 XBP_NO_GROUP     *)  Dialog element does not belong to a group
 XBP_BEGIN_GROUP      Dialog element is the first in a group
                      (this begins the definition of the group)
 XBP_WITHIN_GROUP     Dialog element is within a group
 XBP_END_GROUP        Dialog element is the last in a group
                      (this ends the definition of the group)

*) Default value

GROUP <cGroup> is a "group" name (case-sensitive) to assign to
this GetList object.  Assignment to a group makes it possible to
perform operations only on GetList items which are members of a
specified group, using functions such as DC_GetRefresh() or
DC_ReadGui().

VISIBLE determines whether the object is visible immediately after
the call to the method :create() . By default the object follows
the VISIBLE clause of the DCGETOPTIONS command.  Use the
INVISIBLE clause to override the VISIBLE clause of DCGETOPTIONS

EVAL <bEval> is a code block to evaluate after the object is
created.  The object is passed to the code block as a parameter.

Examples:

/*
In this example, a custom command named @..FILEEDIT can be used
to edit an ASCII file.  The command is used with DCREAD GUI and
can be mixed with any other UDC commands or DC* commands.
*/

#define MYGETLIST_FILEEDIT      GETLIST_USER + 1

#command  @ <nRow>,<nCol> FILEEDIT <(cFile)>    ;
                [SIZE <nWidth> [,<nHeight>]]    ;
                [PARENT <oParent>]              ;
                [PRESENTATION <aPres>]          ;
                [OBJECT <oCustom>]              ;
                [COLOR <ncFgC> [,<ncBgC>] ]     ;
                [FONT <cFont>]                  ;
                [MESSAGE <cMessage>]            ;
                [HELPCODE <cHelpCode>]          ;
                [TOOLTIP <cToolTip>]            ;
                [<p:PIXEL>]                     ;
                [TITLE <cTitle>]                ;
                [RELATIVE <oRel>]               ;
                [ID <cId>]                      ;
                [ACCELKEY <nAccel>]             ;
                [<ro:READONLY>]                 ;
  =>                                            ;
   AADD( GetList,                                       ;
    { MYGETLIST_FILEEDIT,   /* nGETLIST_TYPE         */ ;
      nil,                  /* nGETLIST_SUBTYPE      */ ;
      nil,                  /* cGETLIST_CAPTION      */ ;
      nil,                  /* bGETLIST_VAR          */ ;
      <nRow>,               /* nGETLIST_STARTROW     */ ;
      <nCol>,               /* nGETLIST_STARTCOL     */ ;
      nil,                  /* nGETLIST_ENDROW       */ ;
      nil,                  /* nGETLIST_ENDCOL       */ ;
      <nWidth>,             /* nGETLIST_WIDTH        */ ;
      <nHeight>,            /* nGETLIST_HEIGHT       */ ;
      <cFont>,              /* cGETLIST_FONT         */ ;
      nil,                  /* cGETLIST_PICTURE      */ ;
      nil,                  /* bGETLIST_WHEN         */ ;
      nil,                  /* bGETLIST_VALID        */ ;
      <cToolTip>,           /* cGETLIST_TOOLTIP      */ ;
      nil,                  /* xGETLIST_CARGO        */ ;
      <aPres>,              /* aGETLIST_PRESENTATION */ ;
      nil,                  /* bGETLIST_ACTION       */ ;
      nil,                  /* oGETLIST_OBJECT       */ ;
      nil,                  /* xGETLIST_ORIGVALUE    */ ;
      <.ro.>,               /* xGETLIST_OPTIONS      */ ;
      [{<ncFgC>,<ncBgC>}],  /* aGETLIST_COLOR        */ ;
      <cMessage>,           /* cGETLIST_MESSAGE      */ ;
      <cHelpCode>,          /* cGETLIST_HELPCODE     */ ;
      nil,                  /* cGETLIST_VARNAME      */ ;
      nil,                  /* bGETLIST_READVAR      */ ;
      nil,                  /* bGETLIST_DELIMVAR     */ ;
      [{DC_GetAnchorCB(@<oCustom>,'O'),                 ;
        <(oCustom)>,'O'}],  /* bGETLIST_GROUP        */ ;
      nil,                  /* nGETLIST_POINTER      */ ;
      [{DC_GetAnchorCB(@<oParent>,'O'),                 ;
         <(oParent)>,'O'}], /* bGETLIST_PARENT       */ ;
      {|a|MyFileEditor(a)}, /* bGETLIST_REFVAR       */ ;
      nil,                  /* lGETLIST_READONLY     */ ;
      <.p.>,                /* lGETLIST_PIXEL        */ ;
      nil,                  /* nGETLIST_CURSOR       */ ;
      nil,                  /* bGETLIST_EVAL         */ ;
      [{DC_GetAnchorCb(@<oRel>,'O'),                    ;
         <(oRel)>,'O'}],    /* bGETLIST_RELATIVE     */ ;
      <(cFile)>,            /* xGETLIST_OPTIONS2     */ ;
      nil,                  /* xGETLIST_OPTIONS3     */ ;
      nil,                  /* xGETLIST_OPTIONS4     */ ;
      nil,                  /* xGETLIST_OPTIONS5     */ ;
      nil,                  /* xGETLIST_OPTIONS6     */ ;
      nil,                  /* xGETLIST_OPTIONS7     */ ;
      nil,                  /* xGETLIST_OPTIONS8     */ ;
      nil,                  /* xGETLIST_OPTIONS9     */ ;
      nil,                  /* cGETLIST_LEVEL        */ ;
      <cTitle>,             /* cGETLIST_TITLE        */ ;
      nil,                  /* cGETLIST_ACCESS       */ ;
      nil,                  /* bGETLIST_COMPILE      */ ;
      <cId>,                /* cGETLIST_ID           */ ;
      nil,                  /* dGETLIST_REVDATE      */ ;
      nil,                  /* cGETLIST_REVTIME      */ ;
      nil,                  /* cGETLIST_REVUSER      */ ;
      nil,                  /* bGETLIST_HIDE         */ ;
      <nAccel>,             /* nGETLIST_ACCELKEY     */ ;
    } )

LOCAL GetList := {}

@ 1,0 DCSAY "This is my README.TXT file"

@ 3,0 FILEEDIT C:\express\readme.txt SIZE 60,10

DCREAD GUI ;
   FIT ;
   BUTTONS DCGUI_BUTTON_OK + DCGUI_BUTTON_CANCEL

RETURN nil

/* ----------------------- */

STATIC FUNCTION MyFileEditor ( aParams )

LOCAL oXbp, aGetList, nPointer, oParent, aPos, aSize, aPres, lVisible, ;
      cFileName, cMemo, bAnchor

aGetList    := aParams[1]
nPointer    := aParams[2]
oParent     := aParams[3]
aPos        := aParams[4]
aSize       := aParams[5]
aPres       := aParams[6]
lVisible    := aParams[7]

oXbp      := XbpMLE():new( oParent, , aPos, aSize, aPres, lVisible )

cFileName := aGetList[nPointer,xGETLIST_OPTIONS2]
oXbp:editable := !aGetList[nPointer,xGETLIST_OPTIONS]

IF Valtype(cFileName) = 'C' .AND. File(cFileName)
  cMemo := MemoRead(cFilename)
  aGetList[nPointer,xGETLIST_CARGO] := cMemo
ELSE
  cMemo := 'File: ' + cFileName + ' not found.'
  oXbp:editable := .f.
ENDIF

bAnchor := AnchorCb(@cMemo)

IF Valtype(aGetList[nPointer,cGETLIST_FONT])='C'
  oXbp:SetFontCompoundName(aGetList[nPointer,cGETLIST_FONT])
ENDIF

oXbp:clipSiblings := .T.
oXbp:datalink := bAnchor
oXbp:create()
oXbp:SetData()
IF oXbp:editable
  oXbp:killInputFocus := ;
       {|a,b,o|o:GetData(),MemoWrit(cFileName,cMemo)}
ENDIF

RETURN oXbp
*

Files:

DCUDC.CH

See Also:

   @ DCCUSTOM
   DCUDC.CH


dc_printergroupeject()

Preview the next print group

DC_PrinterGroupEject() is used to allow for previewing of print jobs in "groups" of pages. For example, this can be used to step through a set of invoices in which each invoice may have a different number of pages. Each previewed invoice will be a "group" of pages. <br><br>Clicking the "Next" group button will exit the preview window and return a value of DCPRINT_GROUP_NEXT. By testing for this value in the print loop the record pointer can be moved to the next invoice for printing. <br><br>The "Print" button will print only the pages that are part of the group and are visible in the preview window. Each time DCPRINT GROUPEJECT is encountered in the code, control is given to the preview window. If the user clicks on "Top", "Prev", "Next" or "Bottom", the preview buffer is cleared and a respective numeric value is returned to be used for selecting the next group to preview.<br><br><br><br><br><br>

Syntax:

DC_PrinterGroupEject( <oPrinter> ) -> nStatus

Returns:

A numeric value based on the key clicked by the user.

The values are defined in "DCPRINT.CH"

RETURN VALUE          Description
------------------    -------------------------------------------
DCPRINT_GROUP_FIRST   Returned when "Top" button is clicked
DCPRINT_GROUP_PREV    Returned when "Prev" button is clicked.
DCPRINT_GROUP_NEXT    Returned when "Next" button is clicked.
DCPRINT_GROUP_LAST    Returned when "Bottom" button is clicked.
DCPRINT_GROUP_NONE    Returned when "Ok" or "Cancel" button is clicked.

Arguments:

<oPrinter> is the printer object returned by the
DCPRINT ON command or the DC_Printer() class.  If this clause
is not used then the printer object referenced by
DC_PrinterObject() is the default.

Examples:

#include "dcprint.ch"

PROCEDURE XTest

DCPRINT ON PREVIEW NONSTOP HIDE GROUPBUTTONS TO oPrinter

USE INVOICES

DO WHILE .t.

  PrintInvoice(oPrinter) // code to print multiple pages of invoice

  nStatus := DC_PrinterGroupEject(oPrinter)

  IF nStatus == DCPRINT_GROUP_FIRST
    INVOICE->(dbGoTop())
  ELSEIF nStatus == DCPRINT_GROUP_PREV
    INVOICE->(dbSkip(-1))
  ELSEIF nStatus == DCPRINT_GROUP_NEXT
    INVOICE->(dbSkip(1))
  ELSEIF nStatus == DCPRINT_GROUP_LAST
    INVOICE->(dbGoBottom())
  ELSEIF nStatus == DCPRINT_GROUP_NONE
    EXIT
  ENDIF

ENDDO

DC_PrinterOff(oPrinter)

RETURN

Files:

DCPRINT.CH

See Also:

   DCPRINT ON
   DCPRINT GROUPEJECT


DCAPICK

A dialogue for choosing a item from an array pick list.

DCAPICK is used to display a browse-style picklist of an array.<br><br>

Syntax:

@ [ <nTop>, <nLeft> ] DCAPICK <aMenuItems>          ;
           [SIZE <nWidth>, <nHeight>]             ;
           [HEADER <acHeader>]                    ;
           [COLWIDTH <anColWidth>]                ;
           [TITLE <cTitle>]                       ;
           [TAG <anTag> [COLOR <aTagColor>] ]     ;
           [HANDLER <bHandler>]                   ;
           [START <nStart>]                       ;
           [FONT <cFontName>]                     ;
           [PARENT <oParent>]                     ;
           [OWNER <oOwner>]                       ;
           [CENTER>]                              ;
           [MENU>]                                ;
           [TO <nChoice>]                         ;
           [NOVSCROLL]                            ;
           [NOHSCROLL]                            ;
           [PRESENTATION <aPres>]                 ;
           [AUTOSEEKPICTURE <cAutoSeekPicture>]   ;
           [NORESTORE]

Arguments:

<nTop>, <nLeft> are the starting coordinates.  These are text-
base coordinates.  These parameters are not required if the
<lCenter> parameter is used.

<aMenuItems> is an array of character strings to include
in the pick-list.  This may be a single-dimension array or a
multi-dimension array.

SIZE <nWidth> and <nHeight> are the width and height of the
window in text-based coordinates.

HEADER <acHeader> is the heading to place above each column.  If
<aMenuItems> is a single-dimension array, then there is only 1
header, so <acHeader> is a character string.  If <aMenuItems>
is a multi-dimension array, then <acHeader> is an array of
character strings, 1 for each column.

COLWIDTH <anColWidth> is the width of the column(s).  If
aMenuItems> is a single-dimension array, then there is only 1
width, so <anWidth> is a numeric value.  If <aMenuItems> is a
multi-dimension array, then <anWidth> is an array of numeric
values, 1 for each column.

TITLE <cTitle> is the title to place at the top of the window.

TAG <anTag> is an array of logical elements or a single numeric
value.  If <anTag> is an array, it must be the same length as
the array being browsed and must contain logical values.  When
the user double-clicks a browse row, the corresponding element
of <anTag> will be toggled.  If <anTag> is a numeric value, then
it is a pointer to the column of <aMenuItems> that contains
logical tags.

COLOR <aTagColor> is used in conjunction with <anTag> to select
the color for the rows that are tagged.  This is a 2-element
array consisting of a foreground and background color.  The
default is { GRA_CLR_WHITE, GRA_CLR_BLUE }.

HANDLER <bHandler> is a SPARE.

START <nStart> is a SPARE.

FONT <cFontName> is the font to use for the browse.

PARENT <oParent> is the parent object to create the browse.  If
no parameter is passed, a dialog window will be created.

OWNER <oOwner> is the owner object of the browse.  If no
parameter is passed, the owner will be the same as the parent.

CENTER will center the browse dialog on the desktop.

MENU will enable "menu mode".  This allows the operator to press
keyboard keys that match the first letter of each array item to
select the item.

NOVSCROLL will suppress the vertical scroll bar.

NOHSCROLL will suppress the horizontal scroll bar.

PRESENTATION <aPres> is a presentation array that conforms to
the presentation parameters required for the XbpBrowse() class.

TO <nChoice> is the name of a variable to store the choice
selected by the user.

AUTOSEEKPICTURE <cAutoSeekPicture> if passed will cause an
autoseek GET to be created above the browse window.  The value
entered into the get will be passed to DC_BrowseAutoSeek() to
seek to a value.  <cAutoSeekPicture> establishes the picture clause
for the Get.

NORESTORE will override DC_AutoRestoreWindow() and insure that
the window coordinates and size are never saved and restored.

Examples:

FUNCTION XTest()

LOCAL aDir := Directory(), i, aHeaders, aWidths

FOR i := 1 TO Len(aDir)
  ASize(aDir[i],5)

  aDir[i,5] := .f.
NEXT

aHeaders := { 'File Name', 'File Size', 'File Date', 'File Time' }

aWidths := { 10,10,10,10 }

DCAPICK aDir ;
   SIZE 50,10 ;
   HEADER aHeaders ;
   COLWIDTH aWidths ;
   TAG 5 COLOR { GRA_CLR_WHITE, GRA_CLR_RED } ;
   FONT '8.Terminal'
   TITLE "Disk Directory" ;
   CENTER ;
   TO nChoice

RETURN nChoice

Files:

DCDIALOG.CH

See Also:

   dc_apick()
   dc_achoice()


DCREPORT FORM

A Windows compatible replacement for REPORT FORM

DCREPORT FORM provides the same functionality as the Clipper REPORT FORM command, in that it uses .FRM files, except that it allows for printing to any Windows print device like local and network printers or fax. It also provides the option of "previewing" the printed output.

Syntax:

DCREPORT FORM <frm> ;
         [HEADING <heading>]  ;
         [PLAIN] ;
         [NOEJECT] ;
         [SUMMARY] ;
         [NOCONSOLE] ;
         [TO PRINTER] ;
         [TO FILE <(toFile)>] ;
         [FOR <for>] ;
         [WHILE <while>] ;
         [NEXT <next>] ;
         [RECORD <rec>] ;
         [REST] ;
         [ALL] ;
         [XBP] ;
         [TITLEFONT <titlefont>] ;
         [HEADFONT <headfont>] ;
         [SIZE <nRows>,<nCols>] ;
         [FONT <font>] ;
         [PREVIEW] ;
         [PRINTER @<oPrinter>] ;
         [TEXTONLY] ;
         [ACROBAT] ;

         [OPTIONS <aDefaultOptions>]
                                                                          ;

Arguments:

<xcReport> is the name of the report form (.frm) file that contains
the definition of the REPORT.  If an extension is not specified, (.frm)
is assumed.  <xcReport> can be specified as a literal string or as a
character expression enclosed in parentheses.

TO PRINTER echoes output to the printer.

TO FILE <xcFile> echoes output, without formfeed characters (ASCII
12), to a file.  If a file extension is not specified, a (.txt) is
added.  You can specify <xcFile> as a literal string or as a
character expression enclosed in parentheses.

NOCONSOLE suppresses all REPORT FORM output to the console.  If not
specified, output automatically displays to the console unless SET
CONSOLE is OFF.

<scope> is the portion of the current database file to report.  The
default scope is ALL.

WHILE <while> specifies the set of records meeting the
condition from the current record until the condition fails.

FOR <for> specifies the conditional set of records to report
within the given scope.

NEXT <next> is the number of records to print.

REST will print the remaining records to the end of file.

ALL will print all records.

RECORD <rec> will print only record number <rec>.

PLAIN suppresses the display of the date and page number, and
causes the report to print without page breaks.  In addition, the
report title and column headings display only at the top of the
report.

HEADING places the result of <cHeading> on the first line of each
page.  <cHeading> is evaluated only once at the beginning of the
report, before the record pointer is moved.  If both PLAIN and
HEADING are specified, PLAIN takes precedence.

NOEJECT suppresses the initial page eject when the TO PRINTER
clause is used.

SUMMARY causes the REPORT FORM to display only group, subgroup,
and grand total lines.  Detail lines are suppressed.

XBP causes the form to be printed using the XbpPrinter() class
rather than the standard LPTx device.  If option is not specified
then the remaining arguments are ignored and the printed output
follows path established by standard text-based commands like
SET PRINTER TO <cPath>.  If XBP is specified, then a printer dialog
will be displayed which gives the user the option of directing the
printed output to a Windows device.

FONT <cFont> is the font to use for the body of the report.

TITLEFONT <cTitleFont> is the font to use for the title of the
report.

HEADFONT <cHeadFont> is the font to use for the column headings.

SIZE <nRows, nCols> is the number of rows and columns on the
printed page.  This does not override the settings in the .FRM
file but instead is used to determine establish a pixel resolution
for the page.  For example, if the report uses 132-character
columns, it is recommended that you also use 132 columns as the
size.  If a large number is used, the report will be more
compressed.

PREVIEW will display the report within a window and allow the
user to preview the output on the screen rather than sending it
to the printer.

PRINTER @<oPrinter> is a printer object created with the DCPRINT ON
command.  If this clause is not used or <oPrinter> is initalized
to a NIL then a new printer object will be created an stored in
<oPrinter>.

TEXTONLY will output the report in text-only mode.  The user will
be prompted for the name of a text file to create unless the
TO FILE <xcFile> clause is used.  Only text commands will be
processed in TEXTONLY mode.

ACROBAT is used to invoke Acrobat Reader as the the print
previewer for a much more WYSIWIG preview of the print job.
To use this clause both the Acrobat Reader 5.0
(http://www.adobe.com) and the Win2PDF driver
(http://daneprarie.com) must be installed. The Acrobat
Reader is free and the Win2PDF driver is $39.00.  The demo
version is included.  The Win2PDF driver works only on
Windows NT, 2000 and XP.

OPTIONS <aDefaultOptions> is used to establish the default
options for print jobs.  <aDefaultOptions> is an array that was
previously created by the DCPRINT OPTIONS command.

Examples:

#include "dcprint.ch"

PROCEDURE XTest( lPreview )

lPreview := IIF( Valtype(lPreview)='L',lPreview,.t.)

USE collect NEW
GO TOP

DCPRINT OPTIONS ;
   FONT '8.Courier New' ;
   SIZE 60,132 ;
   NAME 'Win2PDF' ;
   TO aAltOptions

IF lPreview
  DCREPORT FORM collect XBP FONT '10.Courier' ;
       TITLEFONT '10.Helv.Bold' HEADFONT '10.Courier.Bold' PREVIEW ;
       OPTIONS aAltOptions
ELSE
  DCREPORT FORM collect XBP FONT '10.Courier' ;
       TITLEFONT '10.Helv.Bold' HEADFONT '10.Courier.Bold' ;
       OPTIONS aAltOptions
ENDIF

RETURN

Files:

DCPRINT.CH

See Also:

   DCPRINT ON


dc_setwindowtransparency()

Sets a Dialog Window to any transparency from 0% to 100%

DC_SetWindowTransparency() will set a dialog window to any transparency from 0% to 100%.

Syntax:

DC_SetWindowTransparency( <oDlg>, ;
                          <nPercent> ) -> Nil

Returns:

Nil.

Arguments:

<oDlg> is an object that is derived from the XbpDialog class and
is currently hidden with the :hide() method.

<nPercent> is the amount of transparency.

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_zoomtransparent()


DCSTD.CH

The "Standard" command set

The DCSTD.CH file is an "include" file that is used to pre-process miscellaneous commands and dot-prompt commands.<br><br> This is the "standard" command set that is basically equivalent to Alaska's STD.CH. This command set overloads some commands in STD.CH to provide extra functionality, such as progress bars in database commands.<br><br> DCSTD.CH is automatically loaded the first time a command is entered at the dot-prompt. This file must exist in your INCLUDE=<include> path or an error window will be displayed the first time you try to enter a command.

Files:

DCSTD.CH

See Also:

   DC_Dot()


AEDIT

Edit an Array

AEDIT is a full-screen (text-mode) array editor that allows editing of any type of multidimensional array.<br><br>

Syntax:

AEDIT < array >

Arguments:

<array> is the name of any multidimensional array or subarray to
edit.  If this command is used at the dot-prompt, the array
must be a private or public variable.

Examples:

 . aDir := directory()
 . AEDIT aDir

Files:

DCSTD.CH

See Also:

   AVIEW


AEVAL

Evaluate an Array

AEVAL functions identically to the AEVAL() function except the expressions do not need to be code blocks.<br><br>

Syntax:

AEVAL <array> [,<parameter>] [DO] <xpr list> ;
  [START <elem>] [COUNT <elems>]

Arguments:

<array> is the name of the array to evaluate.

<parameter> is an optional parameter used by expressions in
the expression list.

<xpr list> is a list of expressions (separated by commas) to
evaluate for each array element.

START <elem> is the starting element number.

COUNT <elems> is the number of elements to evaluate.

Examples:

 . DIR := DIRECTORY()
 . AEVAL DIR QOUT(DIR[1],DIR[2]) START 10 COUNT 5

Files:

DCSTD.CH


APPEND

Append and Edit a new record

APPEND adds a new record to the currently selected database and then invokes the full-screen (text-mode) editor.

Syntax:

 APPEND

Arguments:

None.

Examples:

 . USE COLLECT
 . APPEND

Files:

DCSTD.CH

See Also:

   APPEND FROM


APPEND BLANK

Append a Blank record

APPEND BLANK will append a blank record to the currently selected database. This functions identical to the Xbase++ APPEND BLANK command except it automatically locks and unlocks the record.

Syntax:

 APPEND BLANK

Arguments:

None.

Examples:

 . USE COLLECT
 . APPEND BLANK
 . EDIT

Files:

DCSTD.CH

See Also:

   APPEND


APPEND FROM

Append records from another file

APPEND FROM works identical to the Xbase++ APPEND FROM command except a progress odometer will display the number of records scanned and the number of records that were actually appended if using the FROM option.<br><br>

Syntax:

APPEND FROM <file> [ <args> ]

Arguments:

See the Xbase++ documentation for details about <args>.

Examples:

. USE COLLECT
. APPEND FROM JUNK

Files:

DCSTD.CH

See Also:

   APPEND


APPEND VIRTUAL

Append Virtual Record to selected database

APPEND VIRTUAL will append the virtual record to the currently selected database. The virtual record must first exist in the form of a *.DCV file originally created by the SAVE VIRTUAL command or DC_VirtSave() function.

Syntax:

APPEND VIRTUAL

Arguments:

None

Examples:

. USE COLLECT
. GO 10
. SAVE VIRTUAL
. APPEND VIRTUAL

Files:

DCSTD.CH

See Also:


AVERAGE

Average numeric fields in selected database

AVERAGE is used to average numeric fields in the currently selected database based on a set of conditions. This command functions identical to the Xbase++ AVERAGE command with the exception that a progress bar is displayed during the averaging and the number of records actually averaged is displayed.<br><br> If no arguments are given, then AVERAGE uses the DC_Average() function to display a GUI dialog for selecting fields and options.<br><br>

Syntax:

 AVERAGE [ <args> ]

Arguments:

 See the Xbase++ documentation for details about <args>.

Examples:

 . USE COLLECT
 . AVERAGE orig_price TO nPrice
 . AVERAGE

Files:

DCSTD.CH

See Also:

   dc_average()


AVIEW

A Tree style array/object browser

AVIEW is used to browse multidimensional arrays and/or objects using a Tree-View style browser.<br><br> The array can be any type of array with any dimensions and may contain any type of data. When expanding the array tree, the user has the option of opening a new window to display the contents of the sub-tree. When expanding an object, the user has the option of displaying the properties of the object using DC_InspectObject().<br><br><br><br>

Syntax:

 AVIEW  aArray | oObject [EXPAND]

Returns:

 NIL.

Arguments:

<aArray> is any type of array.

<oObject> is any type of object.

EXPAND will expand all elements in the tree.

Examples:

 . aDir := directory()
 . AVIEW aDir EXPAND

Files:

DCSTD.CH

See Also:

   dc_arrayview()
   dc_inspectobject()


BATCH

Process a Batch file with Dot-Prompt commands

BATCH execute all commands in a .DCB batch file in sequential order. A batch file can include any commands which can be entered at the dot-prompt and executed by the eXPress++ interpreter other than structural commands, like DO WHILE, DO CASE IF..ENDIF or FOR..NEXT. All commands in DCSTD.CH, DCDIALOG.CH, or DCCUSTOM.CH may be used in batch files.

Syntax:

BATCH [NEW] <batch file> ;
   [ <param1> [ <param2> [ <param3> [ <param4> [ <param5> ]]]]]

Arguments:

<batch file> is the name of the batch file to execute.  If no
extension is given, then .DCB is assumed.  If no directory
path is included, then eXPress++ will search the current
directory followed by the directory established in the SET
DCLIP=<directory> environment command.

NEW will run the batch file in a new thread.

<param1> - <param5> are arguments which are replaced in the
batch file by %1 - %5 in the same manner as replacement is
accomplished in DOS .BAT files.

Notes:

DC_Dot() will automatically execute an AUTOEXEC.DCB batch file found in the directory containing the executable program or the or the directory named by the dos SET DCLIP=<directory> environment setting.

Examples:

 . BATCH OUTPUT MYFILE.PRG PRN

// start up the same browse in two different threads
 . BATCH NEW BROWSE
 . BATCH NEW BROWSE

Files:

DCSTD.CH

See Also:

   DC_Batch()
   DC_BatchNewThread()


BLANK

Blank record(s) in currently selecte database

BLANK is used to blank out all fields in selected records of the current work area.

Syntax:

BLANK [FOR <lCondition] ;
      [WHILE <lCondition>] ;
      [NEXT <nRecords>] ;
      [RECORD <nRecNo>] ;
      [REST] ;
      [ALL]

Arguments:

See the Xbase++ documentation for information on how to use the
FOR, WHILE, NEXT, ALL, REST, and RECORD clauses.

If no arguments are used, only the current record will be
blanked.

Examples:

 . BLANK FOR deleted()
 . BLANK FOR user_id='GOOFY'
 . BLANK

Files:

DCSTD.CH

See Also:

   dc_blank()


BROWSE

A text-base Database browsing system

BROWSE is a multi-windowing database manager that utilizes a browse-style menu for viewing, printing or editing databases.<br><br> BROWSE maintains a multi-dimensional array of information for all open work areas which is remembered even after the browse is exited. When the BROWSE command is used again in any work area which was previously browsed, the browse configuration (including field pointers, column configuration, etc.) will automatically be restored.<br><br> BROWSE is a complete DBMS system that supports a set of pop-up menus for selection of files, viewing options, editing options, printing options, search options, and utilities.<br><br> BROWSE supports importing/exporting, cut and paste and a built-in support for replaceable database drivers (DBE's). Databases of different types may be opened in different windows and macros can be created to easily move data between fields and records from any database window.<br><br>

Syntax:

BROWSE [PROTECT] ;
       [EDIT] ;
       [CLEAR [ALL]] ;
       [FIELDS <fields,...>] ;
       [HEADERS <headers,...>] ;
       [DEFAULT] ;
       [RESTORE [FROM] <cBrowName>]
       [OVERLAY]

Arguments:

EDIT will re-paint all previously created Editing Screens
that were created with the EDIT command.

FIELDS <fields> is a list of fields to browse.  If no field
list is passed, then all fields will be included in the
browse.

HEADERS <headers> is a list of headers that matches the list
of fields to browse.  If no header list is passed, then the
headers will default to the field names.

CLEAR will clear any previously configured browse window for
the current work area and create a browse window with the
default configuration using the full screen and all fields.

CLEAR ALL will clear all browse windows for all work areas.

PROTECT will protect data from being modified by the user.

DEFAULT will display a default browse even if there is a
browse in the Browse dictionary that matches the alias name
of the browse.  A default browse is a one that displays all
fields.

RESTORE FROM <cBrowName> will restore a specified browse
from the Browse dictionary.  <cBrowName> is the name of the
browse to restore.  This stored browse configuration much
match the field names of the current database or an error
will occur.

OVERLAY will display the browse screen over any existing
screens.  If this clause is not used, then the screen will
be cleared first.

Examples:

 . USE CUSTOMER
 . BROWSE CUST_NAME, BALANCE

Files:

DCSTD.CH

See Also:

   dc_browsedb()


CALC

A popup, full-function calculator

CALC displays a GUI calculator.

Syntax:

 CALC

Arguments:

 None.

Examples:

 . CALC

Files:

DCSTD.CH

See Also:

   dc_popcalc()


CD_CHDIR

Change system directory

CD is used to select a new system drive and directory.

Syntax:

 CD | CHDIR <dir>

Returns:

.

Arguments:

<dir> is the drive and directory to select.

Examples:

 . C:
 . CD \express\lib
 . CD ..\sample

Files:

DCSTD.CH

See Also:

   dc_chdir()


CHR

Display an ASCII Character Chart

CHR will display a chart of the 256 ASCII text-mode characters in a new CRT window.

Syntax:

 CHR

Arguments:

 None.

Examples:

 . CHR

Files:

DCSTD.CH

See Also:

   dc_chrsel()


CLEAR SCOPE

Clear scoping values for the current work area

CLEAR SCOPE is used to clear both the SCOPETOP and SCOPEBOTTOM "scoping range" values that were previously set by SET SCOPE or DC_SetScope().<br><br>

Syntax:

 CLEAR SCOPE

Arguments:

 None.

Notes:

SET SCOPE does not establish the scoping range at the DBE-layer level, but instead is just a handy way of storing the SCOPE TOP and SCOPE BOTTOM to be retrieved by programs that can use this information such as data-entry systems and browse systems. It does not affect the behavior of the data-driver nor does it set any filters on the data.

Examples:

 . SET SCOPETOP TO 'B'
 . SET SCOPEBOTTOM TO 'D'
 . BROWSE
 . CLEAR SCOPE

Files:

DCSTD.CH

See Also:

   dc_clrscope()


CODE EDIT

Edit a Code Table

CODE EDIT is an editor that is used to maintain the DCCODES.DBF dictionary file. Code Tables are groups of records that are loaded into an array pick-list and used in validations when using the eXPress++ data-driven Browse and Edit (data-entry) system. When a "T" validation is used in a field-array, this pops-up a code table pick-list for the operator to choose possible values. Code tables can also be used in custom applications where validations and/or choice boxes are required.<br><br> For example a code table named "POSITION" can be added to provide a picklist of available entries for a field of baseball player positions. They would be entered in a code table as follows:<br><br> 1B - First Base 2B - Second Base 3B - Third Base P - Pitcher SS - Short Stop RF - Right Field LF - Left Field CF - Center Field C - Catcher<br><br> A choice from this table can then be selected by calling DC_CodeGet() in a validation or popup routine.<br><br>

Syntax:

CODE EDIT [ [TABLE] <cTable> ]

Arguments:

<cTable> is the name of the code table in DCCODES.DBF
to load and edit (up to 8 characters).  If no parameter is
passed then a pick-list of available code tables will be
displayed.

Notes:

The DCCODES.DBF file and its indexes will be created by the DC_CodeOpen() function if it they do not already exist.

Examples:

 -- Example 1 --
 // Load a code table from the dictionary and edit it //
 CODE EDIT

 -- Example 2 --
 // Edit code table "POSITION"
 CODE EDIT POSITION

Files:

DCSTD.CH

See Also:

   dc_codeedit()


CODE IMPORT

Import a code table

CODE IMPORT is used to import a code table from the DXCODES.DBF import/export file to the DCCODES.DBF file.<br><br>

Syntax:

CODE IMPORT [table name] | "ALL"]

Returns:

 A logical .TRUE. if the code table was saved, .FALSE. otherwise.

Arguments:

<tablename> is the name of the code table.  This is a name of
up to eight (8) characters.  If a code table name is passed then
the DXCODES.DBF database will be searched and all code table
items that match the code table name will be imported into
DCCODES.DBF.  If no name is passed, then a pick-list of all tables
stored in the DXCODES.DBF database will be displayed.

If ALL is passed as the table name, then all tables in the
DXCODES.DBF will be imported into DCCODES.DBF.

Notes:

The DCCODES.DBF file is the data-dictionary database that contains all code tables. If this file does not exist in your default directory or path then it will be created. The DXCODES.DBF file is the data-dictionary database that contains all code tables that were exported from another system.

Examples:

 . CODE IMPORT ALL

Files:

DCSTD.CH

See Also:

   dc_codeimp()
   CODE EDIT


CODE RENAME

Rename a Code Table

CODE RENAME is used to rename a Code Table.

Syntax:

 CODE RENAME <cTableName> TO <cNewName>

Arguments:

<cTableName> is the name of the table to rename.  This is a
name of up to 10 characters.  If no name is given, then a pick
list of all code tables will be displayed.

TO <cNewName> is the new name.  If no name is given, then a
dialog window will be displayed to enter a new name.

Examples:

CODE RENAME BULLET TO BULLETS

Files:

DCSTD.CH

See Also:

   dc_coderename()
   CODE EDIT


CODE_DELETE

Delete a code table

CODE DELETE is used to delete a code table from the code table file.<br><br>

Syntax:

 CODE DELETE [ <tableName> ]

Arguments:

<tableName> is the name of the code table.  This is a name of
up to eight (8) characters.  If no argument is passed, then a
pick list of all code tables in the code table file will be
displayed.

Notes:

The DCCODES.DBF file and its indexes will be created by the DC_CodeOpen() function if it they do not already exist.

Examples:

 CODE DELETE POSITION

Files:

DCSTD.CH

See Also:

   dc_codedelete()
   CODE EDIT


COMPILE

Compile a source .PRG or all changed .PRGs

COMPILE | XPP compiles a specified .PRG file into an .OBJ file or recompiles all .PRG files which have been modified and have a later date/time stamp than their associated .OBJ file.<br><br> Use COMPILE | XPP after editing your source files. COMPILE | XPP checks the date and time stamp on .PRG files and compares them to the date and time on any corresponding .OBJ files. If the date and/or time on a .PRG is later than the corresponding .OBJ, the .PRG will be compiled with the /m option.<br><br>

Syntax:

 COMPILE [ <filename> ], ;
         [OPTIONS <options>], ;
         [QUIET], ;
         [NOWINDOW], ;
         [RECOMPILE]

Arguments:

<filename> is the name of the file to compile.  If this
argument is left blank, then all .PRG files which have a later
date stamp than the associated .OBJ file will be compiled.

OPTIONS <options> is a string of compiler options.  If no argument is
given, then the options established by DC_SETT('XPPOPT',<cOptions>),
SET XPPOPT TO <cOptions> or XPPOPT=<cOptions> (DCLIP.SYS) are
used as the default.

QUIET will prevent displaying the status after compiling.

NOWINDOW will suppress the display a window showing the compiled
results.

RECOMPILE will force a recompile of <filename> regardless of
the date/time of <filename>.  If this clause is not used,
then <filename> will be compiled only if it's date/time stamp
is later than the date/time stamp of it's associated. .OBJ file.

Notes:

If <cFileName> contains a full-path specification of a .PRG file, then the compiled .OBJ will be created in the same directory as the .PRG file unless the /o compiler switch is used to direct the output.

If <cFileName> does not contain a full path then the .PRG file must exist in the current directory or the directory established by DC_SETT('PDIR',<cPath>), SET PDIR TO <cPath> or PDIR=<cPath> (DCLIP.SYS).

If <cFileName> does not contain a full path or the /o compiler switch is not used, then the compiled .OBJ will be created in the directory established by DC_SETT('ODIR',<cPath>), SET ODIR TO <cPath> or ODIR=<cPath> (DCLIP.SYS).

Examples:

 accept 'Enter a file to edit and compile' TO cFile
 dc_editprg(cFile)
 DC_COMPILE(cFile,'/n/m/w/l')

Files:

DCSTD.CH

See Also:

   dc_compile()


CONTINUE

Continue Locating a record

CONTINUE is a front-end to the Xbase++ CONTINUE command. It functions identically with the exception that it stays within any scope that was previously set with SET SCOPE or DC_SetScope().<br><br>

Syntax:

 LOCATE [ <clauses> ]

Arguments:

 See the Xbase++ documentation for a description of <clauses>.

Examples:

 . USE EXPRESS VIA FOXCDX
 . LOCATE FOR COMMAND = 'dc_dot'

Files:

DCSTD.CH

See Also:

   dc_dbcontinue()
   dc_dblocate()


COPY_TO

Copy records from selected database to a new database

COPY TO is used to copy records from the currently selected database to a new database based on a set of conditions. This command function identical to the Xbase++ COPY TO command with the exception that a progress bar is displayed during the copy and the number of records actually copied is displayed.<br><br>

Syntax:

 COPY TO [ <args> ]

Arguments:

 See the Xbase++ documentation for details about <args>.

Examples:

 . USE COLLECT
 . COPY TO JUNK FOR RecNo() > 5

Files:

DCSTD.CH


COPYNEW

Copy only new files to another directory

COPYNEW is used to copy a file or set of files to another directory only if they are newer than the sames files in the destination directory.<br><br> A dialog window will display the status of all files copied.

Syntax:

 COPYNEW <cFromSpec> TO <cToSpec>

Arguments:

<cFromSpec> is the specification of the file(s) to copy from.
If this argument is not given, then a dialog will be displayed
prompting the user for the file specification.

<cToSpec> is the specification of the directory to copy to.
If this argument is not given, then a dialog will be displayed
prompting the user for the directory specification.

Examples:

 COPYNEW *.TXT TO C:\express\sample

Files:

DCSTD.CH

See Also:

   dc_copynew()


COUNT

Count records in selected database

COUNT is used to count records from the currently selected database based on a set of conditions. This command functions identical to the Xbase++ COUNT command with the exception that a progress bar is displayed during the copy and the number of records actually counted is displayed.<br><br> If no arguments are passed COUNT will use DC_Count() to display a GUI dialog for selection of conditions.<br><br>

Syntax:

 COUNT [ <args> ]

Arguments:

 See the Xbase++ documentation for details about <args>.

Examples:

 . USE COLLECT
 . COUNT FOR RecNo() > 5
 . COUNT
 . COUNT TO nCount

Files:

DCSTD.CH

See Also:

   dc_count()


CREATE

Create a new database

CREATE is used to create a new database from a menu in which the user is prompted for entering field names, types, lengths, etc.<br><br> The currently selected default DBE is used when the new database is created.<br><br><br><br>

Syntax:

 CREATE <database>

Arguments:

<database> is the name of the new database to create.  If you
do not include an extension, then the default extension for the
currently selected database driver will be used.

Examples:

 . SET DBE TO FOXCDX
 . CREATE JUNK

Files:

DCSTD.CH

See Also:

   dc_create()


CRT

Run a text-based procedure in a new CRT Window

CRT is used to run a text-based procedure in a new CRT Window.<br><br> The function DC_CrtRunWindow() is used to store a pointer to any existing XbpCrt() class window to use. If this function returns anything other than an XbpCrt() object, then a new CRT window is created before the code block is evaluated and then destroyed after returning from the code block.

Syntax:

 CRT <bBlock> [TITLE <cTitle>] ;
              [COLOR <cColorString>]

Arguments:

<bBlock> is the code block to evaluate after the CRT window
is created or selected.

TITLE <cTitle> is the title to place into the title bar of the CRT
window.

COLOR <cColorString> is the color to clear the CRT window.

Examples:

 . CRT {||DC_ChrSel()} TITLE 'ASCII Chart' COLOR 'N/W'

Files:

DCSTD.CH

See Also:

   dc_crtrun()


DATACONVERT

Convert a database to a different DBE driver

DATACONVERT is used to convert a database to use another DBE driver.

Syntax:

 DATACONVERT <cFileName> ;
       FROMDBE <fromDBE> ;

       TODBE <toDBE>] ;
       EXTENSION <ext>

Arguments:

<filename> is the name of the database to convert.  If this
argument is not passed a GUI dialog window will be displayed to
enter information required.  Enter ALL to convert all databases
with a specified extension.

<fromDBE> is the DBE to use to open <cFileName>.

<toDBE> is the DBE to use to create the converted file.

<ext> is the extension to use when using ALL as the file name.

Examples:

 // convert all files that have a .DBT memo file.
 . DATACONVERT COLLECT FROMDBE DBFNTX TODBE FOXCDX EXTE .DBT

 // convert all files that have a .DBF extension
 . DATACONVERT ALL FROMDBE DBFNTX TODBE DBFCDX EXTE .DBF

Files:

DCSTD.CH

See Also:

   dc_dataconvert()


DATE

A pop-up calendar for selecting a date

DATE displays a GUI calendar.

Syntax:

 DATE

Arguments:

 None.

Examples:

 . DATE

Files:

DCSTD.CH

See Also:

   dc_popdate()


DELETE

Mark record(s) for deletion

DELETE without arguments is used to mark the current record for deletion. This command is a front-end to the Xbase++ dbDelete() function that automatically locks and unlocks the record to prevent a runtime error on shared databases. <br><br> DELETE with arguments works identical to the Xbase++ DELETE command except a progress odometer will display the number of records scanned and the number of records that were actually deleted.<br><br>

Syntax:

 DELETE [ <args> ]

Arguments:

 See the Xbase++ documentation for <args>.

Examples:

 . USE EXPRESS INDEX EXPRESS.CDX SHARED
 . GO 10
 . DELETE
 . DELETE WHILE RecNo() < 20

Files:

DCSTD.CH

See Also:

   dc_delete()


DELETE TAG

Delete a tag from a combined index

DELETE TAG is used to delete an index tag from a combined index.

Syntax:

 DELETE TAG

Arguments:

 None.

Examples:

 . USE EXPRESS INDEX EXPRESS.CDX EXCL
 . DELETE TAG

Files:

DCSTD.CH

See Also:

   dc_tagdelete()


DELETE_FILE

Delete a file

DELETE FILE is used to delete a file from the disk.<br><br>

Syntax:

 DELETE FILE [ <filename> ]

Arguments:

<filename> is the name of the file to delete. If this argument
is not used then a GUI dialog will be displayed to choose a file.

Examples:

 . DELETE FILE JUNK.PRN
 . DELETE FILE

Files:

DCSTD.CH

See Also:

   dc_erase()


DIR

Display a directory of files or databases

DIR is used to display a directory of files or databases.

Syntax:

 DIR [ <FileSpec> ]

Arguments:

DIR <FileSpec> is the specification of the files to display including
path and extension.  The file dialog shows the file name, date,
size and time.

If no argument is passed, then only .DBF database files will be
displayed.  This dialog allows for the file to be automatically
opened when the item is selected.  The database dialog shows the
file name, date, size, number of records, and type of database.

Examples:

 . DIR       // display all database files
 . DIR *.TXT // display all text files

Files:

DCSTD.CH

See Also:

   dc_dir()


DISPLAY STATUS

Display System status window

DISPLAY STATUS is used to display a scrollable window of information about the system application.<br><br>

Syntax:

 DISPLAY STATUS

Arguments:

 None.

Examples:

 . USE COLLECT INDEX COLLECT
 . DISPLAY STATUS

Files:

DCSTD.CH

See Also:

   dc_status()


DISPLAY STRUCTURE

Display the structure of the selected database

DISPLAY STRUCTURE is used to display the structure of the selected database file. A GUI dialog window displays the structure in a scrollable window with options to Print or save to a File.

Syntax:

 DISPLAY STRUCTURE [WIDE]

Arguments:

WIDE displays the structure in a Wide Window with the data
formatted in the screen to view more fields in the viewable
area of the window.  Use this option when viewing the structure
of databases with many fields.

Examples:

 . USE COLLECT
 . DISPLAY STRUCTURE

Files:

DCSTD.CH

See Also:

   dc_dbstru()
   dc_dbstruw()


DISPLAY_MEMORY

Display the contents of a memory file or current memory

DISPLAY MEMORY is used to display the contents of an .XPF (memory) file or the current contents of memory (PUBLICS/PRIVATES only) in a GUI scrolling browse window.

Syntax:

 DISPLAY MEMORY [FILE cMemFileName]

Arguments:

FILE <cMemFileName> is the name of the memory file.  If no
extension is given then .XPF is assumed.

If no argument is passed then the current contents of memory
are saved to a file named EXPRESS.XPF and the contents of
EXPRESS.XPF are displayed.  NOTE: If any PUBLIC or PRIVATE
memory variables exist containing non-persistent data such as
objects or some type of code blocks, a runtime error will
result and the contents of memory cannot be displayed.

Examples:

 . custname := 'Donnay Software'
 . product := 'eXPress++ 2.0'
 . DISPLAY MEMORY
 . DISPLAY MEMORY FILE PRODUCT.XPF

Files:

DCSTD.CH

See Also:

   dc_xpftoarray()
   dc_dispmem()


DLL LOAD

Load a dynamic .DLL

DLL LOAD is used to load a dynamic .DLL and save away information about the .DLL in a static array to be used later with DLL UNLOAD or DC_DllUnload().

Syntax:

 DLL LOAD [ <cDllName> ]

Arguments:

<cDllName> is the name of the .DLL to load.  If this argument
is not passed a GUI dialog will be displayed prompting for the
name.

Examples:

 . DLL LOAD MYTEST
 . DO test
 . DLL UNLOAD MYTEST

Files:

DCSTD.CH

See Also:

   dc_dllload()


DLL UNLOAD

UnLoad a dynamic .DLL

DLL UNLOAD is used to unload a dynamic .DLL that was previously loaded with DLL LOAD or DC_DllLoad().

Syntax:

 DLL UNLOAD [ <cDllName> ]

Arguments:

<cDllName> is the name of the .DLL to unload.

Examples:

 . DLL LOAD MYTEST
 . DO test
 . DLL UNLOAD MYTEST

Files:

DCSTD.CH

See Also:

   dc_dllunload()
   DLL LOAD


DLL_LIST

List all loaded dynamic .DLLs

DLL LIST is used to list all the dynamic .DLLs that are currently loaded. These .DLLs must have been loaded with DC_DllLoad() or DLL LOAD.

Syntax:

 DLL LIST

Arguments:

<cDllName> is the name of the .DLL to load.  If this argument
is not passed a GUI dialog will be displayed prompting for the
name.

<lMessage> if .TRUE. (default) will display a GUI message box
if the .DLL could not be loaded.

Examples:

 . DLL LOAD MYTEST
 . DLL LOAD MYFUNCS

Files:

DCSTD.CH

See Also:

   dc_dlllist()


EDIT VIRTUAL

Edit the Virtual Record

EDIT VIRTUAL pops up a full-screen (text-mode) editor to modify the contents of the virtual record previously saved by the SAVE VIRTUAL command.<br><br>

Syntax:

 EDIT VIRTUAL

Arguments:

 None.

Examples:

 . USE CUSTOMER
 . GO 10
 . SAVE VIRTUAL
 . EDIT VIRTUAL
 . GO 20
 . REPLACE WITH VIRTUAL

Files:

DCSTD.CH

See Also:


EDIT_FILE

Edit a source file

EDIT FILE is used to edit a source code file. This function will use the editor defined as the "system" editor via the EDITOR= command in DCLIP.SYS, the DC_EDITCONFIG() function or the SET EDITOR command.<br><br> If no external editor is defined, then an imbedded GUI text editor will be used.<br><br>

Syntax:

 EDIT FILE <cFileName> ;
      [LINE <nLineNmbr>] ;
      [ <cParameters> ]

Returns:

 A logical .TRUE. if editor was called successfully.

Arguments:

<cFileName> is the name of the ascii file to edit.  If no
argument is given, then the user will be prompted for the name
of the file. If no extension is included, then .PRG is
assumed.

LINE <nLineNmbr> is the line number to go to.  If no parameter is
passed then the editing will start at line 1.

<cParameters> is an optional set of parameters to pass to the
editor.

Notes:

If the drive and directory is not included in the <cFileName> argument, then DC_EDITPRG() will search for the file first in the SET DCLIP directory followed by the SET PDIR directory (if file is a .PRG).

Examples:

 . dc_editconfig( '\express\util\MEW2.BAT' ) // Multi-Edit (Windows)
 . DC_EDITPRG( 'test' )

Files:

DCSTD.CH

See Also:

   dc_editprg()


FILE EDIT

A Database File / Work area Definition editor

FILE EDIT is an editor that maintains the definition of each database and it's indexes and relations.<br><br> Each file group is stored in the DCFILES.DBF dictionary file. A file group contains all the information necessary to restore work areas for editing and browsing. The data dictionary contains information for opening databases and indexes (or creating indexes that do not exist).

Syntax:

 FILE EDIT [ <acFileGroup> ]

Arguments:

<acFileGroup> is the name of the file group in DCFILES.DBF
to load and edit (up to 8 characters) or <acFileGroup> is a
File Group array.  See DC_FileEdit() (RETURNS) for a specification
of this array.  If no parameter is passed, a pick-list of all
File Groups in DCFILES.DBF will be displayed.

Examples:

 -- Example 1 --
 // Load a file group from the dictionary and edit it //
 . FILE EDIT

 -- Example 2 --
 // Edit file group "CUSTOMER"
 . FILE EDIT GROUP CUSTOMER

 -- Example 3 --
 // Edit a file group array //
 . aFileGroup := DC_FilePik()
 . FILE EDIT GROUP aFileGroup

Files:

DCSTD.CH

See Also:

   dc_fileedit()


FILE IMPORT

Import File Group(s) from the Import File Dictionary

FILE IMPORT is used to import file group configurations from a DXFILES.DBF file into the DCFILES.DBF file.

Syntax:

 FILE IMPORT ;
   [GROUP <cFileGroup> | ALL ]

Arguments:

GROUP <cFileGroup> is the name of the file group.  This is a
name of up to eight (8) digits.  If a group name is passed then
the DXFILES.DBF database will be searched and all group
items that match the group name be imported into DCFILES.DBF.
If no name is passed, then a pick-list of all file groups stored
in the DXFILES.DBF database will be displayed.

If ALL is passed as the group name, then all groups in the
DXFILES.DBF will be imported into DCFILES.DBF.

Notes:

The DCFILES.DBF file is the data-dictionary database that contains all file group configurations. If this file does not exist in your default directory or path then it will be created. The DXFILES.DBF file is the data-dictionary database that contains all file groups that were exported from another system.

Files:

DCSTD.CH

See Also:

   dc_fileimp()


FILE RESTORE

Restore work areas, indexes, relations, from dictionary

FILE RESTORE is used to restore a complete work area environment from a the DCFILES.DBF data dictionary. This function will accomplish the following:<br><br> * Re-open all databases, using the required RDD (Replaceable Data Driver).<br><br> * Open all indexes or rebuild indexes that don't exist or have not been properly updated.<br><br> * Set parent-child relations.<br><br> * Restore record, index and tag pointers.<br><br> * Restore browse windows. (optional)<br><br> * Restore filters.<br><br> * Restore Database environment such as PATH, DEFAULT, UNIQUE, etc.<br><br>

Syntax:

 FILE RESTORE [ <acFileGroup> ], ;
              [ADDITIVE], ;
              [EXCLUSIVE], ;
              [TAG <cTagName>]

Arguments:

<acFileGroup> is the name of a file group in the DCFILES.DBF
dictionary or an array that conforms to the specifications of
the array returned by DC_FileEdit().  If no argument is passed,
a picklist will be displayed.

ADDITIVE is an optional clause which will insure that
currently used work areas are not affected.  If a database is
already opened in a work area, it will not be reopened in a new
work area.  If the <lAdditive> parameter is not passed, then
all work areas will be closed before restoring the old work.

EXCLUSIVE if .TRUE. will override the settings in the DCFILES.DBF
file for the file group and open the files EXCLUSIVE.  If the
parameter is not passed or is .FALSE., then files will be
opened in the default mode.

TAG <cTagName> if passed as a character string or numeric value
will override the tag name or index order in the DCFILES.DBF
file group.

Examples:

 use maillist via 'ADSDBE"
 index on zip tag zip
 index on phone tag phones
 use customer via 'ADSDBE' new index custnmbr
 use invoice via 'ADSDBE' new index invoice
 set relation to cust_nmbr into customer
 FILE SAVE MYWORK
 close all
 FILE RESTORE MYWORK

Files:

DCSTD.CH

See Also:

   dc_filerest()
   FILE SAVE


FILE SAVE

Save Work area definition array to dictionary

FILE SAVE is used to save the contents of a file group array or the current workareas to the DCFILES.DBF data-dictionary.<br><br>

Syntax:

 FILE SAVE [FROM <aFileGroup>] ;
           [WORKAREAS] ;
           [GROUP <cFileGroup>]

Arguments:

FROM <aFileGroup> is a file group array that conforms to the
specification of the array returned by DC_FILEEDIT().

WORKAREAS will save the information about currently open
workareas rather than a passed array. The <aFileGroup>
parameter is not needed and will be ignored if WORKAREAS is
used.

GROUP <cFileGroup> is needed only if the WORKAREAS clause is
used. This is the name of the file group (up to 8 characters)
to assign to the file group.

Examples:

 -- Example 1 --
 /* Save Work areas to file dictionary */
 FILE SAVE WORKAREAS GROUP CUSTOMER

 -- Example 2 --
 /* Edit and Save a file group array //
 cFileGroup := DC_FilePik()
 aFileGroup := DC_FileEdit( cFileGroup )
 FILE SAVE FROM aFileGroup

Files:

DCSTD.CH

See Also:

   dc_filesave()
   FILE RESTORE


FILE_DELETE

Delete a file group from the DCFILES.DBF dictionary

FILE DELETE is used to delete a file group from the DCFILES.DBF file dictionary.

Syntax:

 FILE DELETE ;
     [GROUP <cFileGroup>] )

Arguments:

GROUP <cFileGroup> is the name of the file group in DCFILES.DBF
to delete (up to 8 characters).  If no parameter is passed then
a pick list will be displayed.

Examples:

 // Delete the file group named JUNK
 . FILE DELETE JUNK

Files:

DCSTD.CH

See Also:

   dc_filedel()


FIND

GUI dialog for finding a record using an index

FIND is a high-level command that scans all index keys and creates an input screen to allow the user to find information by simply typing in the value in the box next to the associated index key. This is a quick method of finding information in a database that has multiple index files open or multiple index tags in a combined index.<br><br> After the user enters in the value next to the referenced index, the database is checked to see if more than one record matches the entered value. If duplicates are found, then a pick-list of records is displayed to allow the user to choose one.<br><br>

Syntax:

 FIND

Arguments:

 None.

Examples:

 . USE EXPRESS VIA FOXCDX INDEX EXPRESS.CDX
 . FIND

Files:

DCSTD.CH

See Also:

   dc_find()
   HUNT


GO TOP

Go to the Top of a set of Scoped Records

GO TOP is used to go to the first record in a group of "scoped" records. Scopes are set via the DC_SetScope() function. If a scope is not set, then GO TOP simply calls dbGoTop().<br><br>

Syntax:

 GO | GOTO TOP

Arguments:

 None.

Examples:

 . USE EXPRESS INDEX EXPRESS.CDX
 . SET ORDER TO 'COMMAND'
 . SET SCOPE TOP TO 'C'
 . SET SCOPE BOTTOM TO 'E'
 . GO TOP

Files:

DCSTD.CH

See Also:

   dc_dbgotop()


GO_BOTTOM

Go to the Bottom of a set of Scoped Records

GO BOTTOM is used to go to the first record in a group of "scoped" records. Scopes are set via the DC_SetScope() function. If a scope is not set, then GO BOTTOM simply calls dbGoBottom().<br><br>

Syntax:

 GO | GOTO BOTTOM

Arguments:

 None.

Examples:

 . USE EXPRESS INDEX EXPRESS.CDX
 . SET ORDER TO 'COMMAND'
 . SET SCOPE TOP TO 'C'
 . SET SCOPE BOTTOM TO 'E'
 . GO BOTTOM

Files:

DCSTD.CH

See Also:

   dc_dbgobottom()


HELP

Display HELP for a command or function

HELP will display the help window and optionally go to a specified help item.

Syntax:

HELP [<command>]

Arguments:

<command> is the name of a command or function.

Examples:

HELP
HELP @ DCBROWSE
HELP dc_arrayview()

Files:

DCSTD.CH

See Also:


HUNT

Hunt for a record by search all indexes

HUNT is a method of FINDing a record by searching all open index files or tags for the value entered. This is the quickest method of finding information by scanning all the keys for the first match. The value entered on the command line is automatically converted to the proper "type" to perform the seek. For example, if you entered the command HUNT 12.5, only numeric indexes will be seeked, or if you enter the command HUNT 01/02/03, only date indexes will be seeked. If you enter an expression, such as HUNT DATE()-30, then only the indexes that match the type of the expression entered will be seeked.<br><br> Using HUNT and RESUME is the fastest method of finding information in a large database that uses many index keys. It is recommended that you build a set of keys for all fields that you want to include in the HUNT operation. This can be accomplished easily by using the INDEX FIELDS command to create a set of tags all at one time.<br><br>

Syntax:

 HUNT <xValue>

Arguments:

<xValue> is the value to HUNT.  This can be a value or an
expression. If entered as an expression ( includes quotes or
parenthesis ) it will be evaluated and converted to the proper
value before performing the seek.  If entered as a literal
argument, then a "smart" process in invoked which will
determine the type of argument based on the kind of information
entered.

Notes:

HUNT automatically capitalizes the passed argument, so make sure that your character type indexes are UPPER() case. When building index tags with INDEX FIELDS, this is accomplished automatically.

Examples:

 . USE MAILLIST
 . INDEX FIELDS LAST, FIRST, COMPANY, MAIL_DATE, SOURCE ;
                TO MAILLIST.CDX
 . HUNT COMP
 . RESUME
 . HUNT DATE()
 . HUNT LARRY
 . HUNT EGGHEAD

Files:

DCSTD.CH

See Also:

   FIND
   dc_hunt()


IF_ELSE

Evaluate a list of expressions based on a condition

IF ELSE is a dot-prompt replacement for IF...ELSE...ENDIF programming structure to be used when a single line command is needed.<br><br>

Syntax:

 IF <bIf> DO <bDoIf> ;
    [ELSE <bDoElse>]

Arguments:

<bIf> is a code block to be that is evaluated as the IF
statement.

DO <bDoIf> is a code block that is evaluated if <bIf> evaluates
.TRUE.

ELSE <bDoElse> is a code block that is evaluated if <bIf> evaluates
.FALSE.

Examples:

 . USE COLLECT
 . IF eof() DO DC_MsgBox('End of file') ELSE dbSkip()

Files:

DCSTD.CH

See Also:

   dc_ifelse()


INDEX ON

Create an index

INDEX ON is a front-end to the Xbase++ INDEX ON command and supports all the same options. It functions identically with the exception that it displays a progress bar during the index process.<br><br>

Syntax:

 INDEX ON [ <clauses> ]

Arguments:

 See the Xbase++ documentation for a description of <clauses>.

Examples:

 . USE CUSTOMER
 . INDEX ON CUST_NMBR TO  CUSTNMBR
 . INDEX ON NAME TO CUSTNAME
 . SET INDEX TO CUSTNAME, CUSTNMBR
 . USE COLLECT VIA DBFCDX
 . INDEX ON TYPE TAG TYPE

Files:

DCSTD.CH

See Also:


INDEX_FIELDS

Create index tags for all fields in a database

INDEX FIELDS is used to create an index tag for all fields (up to 99) in a database. This command is handy when you wish to have an index for each field in the database and are using the HUNT..RESUME .or DC_HUNT() "smart seeking" feature of eXPress++.<br><br>

Syntax:

 INDEX FIELDS [ <list> ] ;
       [LENGTH <nLength>] ;
       [TO <cCDXName>]

Arguments:

TO <cCDXName> is the name of the Combined Index file to create.
If no extension is given, then if the default extension for
combined indexes supported by the Data driver in use will be
appended.

If no <cCDXName> name is given, then the index will be created
using the same prefix as the open database and with the default
extension for combined indexes supported by the Data driver in
use.

<list> is a list of index tag names to create, separated by
commas.  The tag name(s) must be the same as the name(s) of
valid fields in the current work area.  If no list is passed
then tags for ALL fields will be created.

LENGTH <nLength> is an optional argument only to determine the
maximum length of character type indexes.  For example, if you
have a character field of 100 bytes, you most likely will not
want to index on all 100 bytes, but instead on only the first
10 characters.  If this argument is not passed, then a default
length of 10 will be used. If the length of any character field
is less than <nLength> then the index length for that specific
tag will be the field length.

Examples:

 . USE MAILLIST VIA DBFCDX
 . INDEX FIELDS "LAST", "COMPANY", "SOURCE"
 . HUNT 'SCOTT'

Files:

DCSTD.CH

See Also:

   dc_tagallcreate()


INKEY

Display Inkey() and AppEvent() values for pressed keys

INKEY is used to display Inkey() and AppEvent() values for keys pressed by the user.<br><br>

Syntax:

 INKEY

Arguments:

 None.

Examples:

 . INKEY

Files:

DCSTD.CH

See Also:

   dc_inkeydsp()
   dc_inkey()


INSERT

Insert Blank or Virtual records in selected database

INSERT will insert a specified number of blank or virtual records into the currently selected database starting at the current record. All records after the current record will be pushed down and the selected number of records will be inserted into the database.<br><br>

Syntax:

INSERT [VIRTUAL] [<nRecords>]

Arguments:

<nRecords> is the number of new records to insert.

VIRTUAL option will replace all new records with the value of
the virtual record created by using the SAVE VIRTUAL command.

Examples:

 . INSERT 20
 . INSERT VIRTUAL 5

Files:

DCSTD.CH

See Also:

   BLANK


INTERP_ARRAY_BROWSE

Browse an array

ABROWSE is a full-screen (text-mode) array browser that gives a full-view of all elements in a multi-dimensional array or object. A symetrical array may be browsed using a columnar style browse or any type of array may be browsed using an indented-style browse.<br><br> Indented style browsing displays sub-elements as automatically indented and the type and value of each element is displayed. Indented-style browsing allows you to change the type, value, or length of any element or sub-element. You can grow or shrink arrays or change elements of any type to an array or arrays to any other type.<br><br><br><br>

Syntax:

ABROWSE < array > [SYMMETRICAL] [NONSYMETRICAL]

Arguments:

<array> is the name of an array to browse.  If this command is
used at the dot prompt, then the array must be public or private.

SYMMETRICAL will browse the array using the columnar-style
browser.

NONSYMMETRICAL will browse the array using the indented-
style browser.

Examples:

 . DIR := DIRECTORY('*.PRG')
 . ABROWSE DIR

Files:

DCSTD.CH

See Also:

   AVIEW
   DC_ArrayView()


INTERP_ASSIGN

Assign new values to field variables

REPLACE works identical to the Xbase++ REPLACE command except a progress odometer will display the number of records scanned and the number of records that were actually replaced. Also, each record is individually locked and unlocked thus allowing REPLACE to be used with shared applications.<br><br> If no arguments are used, then REPLACE displays a GUI dialog so the user may enter the conditions for the replacement.<br><br><br><br><br><br>

Syntax:

 REPLACE [ <args> ]

Arguments:

 See the Xbase++ documentation for the REPLACE command.

Examples:

 . USE COLLECT
 . REPLACE ALL CONDITION WITH 'E'
 . REPLACE

Files:

DCSTD.CH

See Also:

   dc_virtrepl()


INTERP_AUTO_RECLOCK

Toggle automatic File/Record locking

SET AUTOLOCK is used to enable or disable the automatic record- locking feature of eXPress++ when using certain dot prompt commands. Many Xbase++ commands will require a record lock whenever the command modifies data in the current work area. If AUTOLOCK is ON, then the record lock is issued automatically. If AUTOLOCK is OFF, then the DBRLOCK() function or LOCK command must be issued at the dot-prompt otherwise a "lock required" error may be displayed.<br><br> SET AUTOLOCK will not affect any application code or any eXPress++ menus, only commands issued at the dot prompt.<br><br>

Syntax:

SET AUTOLOCK ON | OFF | <lToggle>

Arguments:

ON will automatically lock and unlock the current record or
file whenever a dot-prompt command is issued that requires a
lock. (DEFAULT).

OFF will disable the automatic record-locking feature.

<lToggle> if .T. is equivalent to ON, if .F. is equivalent to
OFF.

Examples:

 . USE SALES SHARED
 . SET AUTOLOCK OFF
 . DELETE
 Lock Required  DBFNTX[1022]
 . SET AUTOLOCK ON
 . DELETE
 . RECALL

Files:

DCSTD.CH


INTERP_BATCH

Create a command to run an executable program

SET COMMAND adds a command verb to a table of commands for running other programs from a single verb command. This is a handy method of creating quick commands to run executable programs.

Syntax:

 SET COMMAND TO <cCommandVerb>, <executable program>

Arguments:

<cCommandVerb> is the name of the command you wish to use at
the dot prompt execute the procedure.

<executable program> is the name of the .EXE to run.

Examples:

 . SET COMMAND TO ME, C:\MEW\MEW32.EXE
 . ME

Files:

DCSTD.CH

See Also:


INTERP_CHILD_RELATION

Set a relation with a child scope

SET RELATION is a front-end to the Xbase++ function dbSetRelation() which defines a link between two work areas. The dependent or child work area is specified by the argument <cAlias> The controlling or parent work area is determined by the alias operator. If the alias operator is not used, the current work area is the parent work area the child area is synchronized with. Existing links in the parent work area are not deleted by SET RELATION. <br><br>The synchronization of the record pointer in the child work area occurs using the return value of <bRelation> . The child work area is automatically searched for this value using DbSeek() anytime the record pointer in the parent work area changes. If no index is active in the child work area, synchronization is done using the function DbGoto(). This means that an attempt is made to set the record pointer in the child work area using the value returned from <bRelation> as a record ID. <br><br>The range for navigating the record pointer in the child work area can be restricted to a subset of records by specifying .T. (true) for the optional parameter SCOPED . In this case, only those records are accessible in the child work area where the link expression <bRelation> results in the same value for both work areas. When attempting to move the record pointer in the child work area outside this defined range, either Bof() or Eof() is set to .T. (true). In this way, a time consuming filter expression can be avoided. <br><br>

Syntax:

 SET RELATION                                  ;
     TO <key1> ;
     INTO <alias1> ;
     [SCOPED]          ;
     [, TO <keyN> INTO <(aliasN)> [SCOPED]]    ;
     [ADDITIVE]

Arguments:

<alias1> through <aliasN> are character string containing the
alias name for the work area(s) to which a link is defined.

TO <key1> through <keyN> are expression(s) used to position the
record pointer in the child work area in order to synchronize it
with the record pointer in the parent work area.  The return
value of the relation is passed to DbSeek() to position the
record pointer in the child work area.

SCOPED will automatically set the scope in the child work area
to the value of the data in the parent work area whenever the
parent record pointer is changed.

ADDITIVE will add the relation to existing relations.  If this
clause is not used then all existing relations will be closed
first.

Examples:

. USE INVOICES
. USE INVITEMS INDEX INVITEMS
. SELECT INVOICES
. SET RELATION TO "01122" INTO INVITEMS SCOPED

Files:

DCSTD.CH

See Also:

   dc_setrelation()


INTERP_CREATE_MENU

Create a new menu with Menu Editor

MENU CREATE is used to create a new menu using the menu editor system - DC_MenuEdit().

Syntax:

 MENU CREATE <cMenuName>

Arguments:

<cMenuName> is the name of the new menu to create.  The menu
will be saved to the DCMENU.DBF dictionary.

Examples:

 . MENU CREATE NEWMENU

Files:

DCSTD.CH

See Also:

   dc_menuedit()


INTERP_DBE_SELECT

Select a database driver

SET DBE | RDD is used to select a database driver (DBE) from a picklist of available drivers.<br><br>

Syntax:

 SET DBE | RDD [TO <cDbe>]

Arguments:

TO <cDbe> is the database driver to select.

Examples:

 . SET RDD TO DBFNTX  // set DBFNTX as the default driver
 . SET RDD // display a list of drivers to select

Files:

DCSTD.CH

See Also:

   dc_rddsel()


INTERP_DOSKEY

Set Dot-Prompt command stack to DOS-Key emulation

SET DOSKEY is used to set the behavior of the dot-prompt command stack navigator to emulate that of DOS command stack navigators like Dos-Key or OS/2.<br><br> The normal behavior allows commands to be reissued in sequence and expedite processes that are used again and again. Dos-Key emulation automatically copies the selected command to the bottom of the stack after execution and creates a blank command line for input.<br><br>

Syntax:

SET DOSKEY on | OFF

Examples:

 . SET DOSKEY ON

Files:

DCSTD.CH


INTERP_ENVIRONMENT

Set and/or view an environment variable

SET is used to set or read an Xbase++ or eXPress++ environment variable.<br><br> SET with no parameters will invoke a GUI editor for observing or modifying the value of any SET value in the environment.<br><br> The SET environment is the complete set of standard Xbase++ SETs such as SET EPOCH, SET DEFAULT, etc. and the additional eXPress++ SETs such as SET ODIR, SET PROMPT, etc.<br><br>

Syntax:

 SET [ <cSetName> ] [TO <xValue>]

Arguments:

<cSetName> is the name of the SET environment variable to
edit.  If this parameter is not passed, then a picklist of all
environment variables will be displayed for editing.

If this is an Xbase++ name such as EPOCH, DATEFORMATE, PATH,
DEFAULT etc. the value will be processed by the Xbase++ Set()
function.

If it is a eXPress++ name such as ODIR, EDITOR, etc, the
value will be processed by the DC_Sett() function.

TO <xValue> is the value to set.

Examples:

 . SET
 . SET DEFAULT
 . SET ODIR
 . SET DEFAULT TO ..\XDOC
 . SET EDITOR TO \MEW\MEW32.EXE

Files:

DCSTD.CH

See Also:

   dc_setedit()


INTERP_FIELD_HOTKEY

Establish the hot key for popping up a field list

The ALT-F key is the default key to invoke the Field List window for selecting a field from the currently selected database and/or relational databases. If you wish to reassign this key to prevent conflict with other hot-keys, then use this command.<br><br>

Syntax:

 SET FLDKEY TO <nInkey>

Arguments:

<nInkey> is the same as the INKEY() value for the desired key
to press to invoke the field pick-list.

Examples:

 // Define ALT-P as the field list key
 . SET FLDKEY TO 281

Files:

DCSTD.CH


INTERP_INTERPRET

Interpret a command string

INTERPRET is a command-line interpreter that will translate and execute any sequence of commands that is supported by Xbase++, eXPress++ and/or any command that has been user defined in DCCUSTOM.CH. INTERPRET requires that the file DCSTD.CH and DCCUSTOM.CH exist in the INCLUDE path of the workstation. The DCSTD.CH file contains all the standard eXPress++ commands and pointers to the Xbase++ include files for the standard Xbase++ commands and defines.<br><br> INTERPRET will execute a single command string or an array of commands that encompass an entire procedure with passed parameters and a return value.<br><br> INTERPRET was designed to work in conjuction with DC_PROGRAM() and/or DC_PROGLOAD() which will load a program from the DCPROG.DBF program catalog, compile the program into a multi-dimensional array, then pass the program to INTERPRET for execution.<br><br> <br><br>

Syntax:

INTERPRET [CLIPBOARD] ;
          [MEMVAR <memvar>] ;
          [FILE <file>] ;
          [WITH <params,...>]

Arguments:

MEMVAR <memvar> is a string containing a set of commands or an
array containing a procedure.  If <memvar> is an array, then it
must conform to the specifications of the array returned by
DC_PROGLOAD(). If this parameter is a NIL, then the Windows
ClipBoard will be used as the program to interpret.  This
allows for cutting code snippets out of a help file, copying
them to the ClipBoard and then interpreting the code snippet.

 - or -

FILE <file> is a text file containing a set of commands.

WITH <params> is a single-dimensional array of parameters to
pass to the program being interpreted.  There should be one
element in the array for each parameter included in the
PARAMETERS statement in the interpreted program.

NOTE: The CLIPBOARD clause or no parameters will use the Windows
      ClipBoard as the source of the program.

Examples:

 . INTERPRET MYPROG.TXT

Files:

DCSTD.CH

See Also:

   dc_dot()
   dc_translate()
   dc_interpret()


INTERP_LOAD_OBJ

Dynamically load an Xbase++ compiled .OBJ for execution

OBJ LOAD is used to "dynamic-link" an Xbase++-compiled .OBJ file into memory for execution of any functions within the compiled .OBJ. This is done by creating a temporary .DLL with the same name as the .OBJ file and loading the .DLL. <br><br>

Syntax:

 OBJ LOAD <cObjName> ;
    [RUN [<bcRunProc>] ]

Returns:

 A logical .TRUE. if the .OBJ file could be linked into a .DLL
 and the .DLL loaded for execution, .FALSE. otherwise.

Arguments:

<cObjName> is the name of the .OBJ file to link.  If no drive/
directory is included in the file name, then the .OBJ must
exist in the directory specified by the SET ODIR command, ODIR=
in DCLIP.SYS, or DC_SETT('ODIR',<path>).

RUN <bcRunProc> will be automatically execute the <bcRunProc>
procedure.  This may be the name of a procedure or function
in quotes or a code block.

Examples:

 . OBJ mytest RUN test

Files:

DCSTD.CH

See Also:

   dc_objload()
   dc_compile()


INTERP_LOCATE

Locate a record

LOCATE is a front-end to the Xbase++ LOCATE command and supports all the same options. It functions identically with the exception that it displays a progress bar during the index process and it also stays within any scope that was previously set with SET SCOPE or DC_SetScope().<br><br>

Syntax:

 LOCATE [ <clauses> ]

Arguments:

 See the Xbase++ documentation for a description of <clauses>.

Examples:

 . USE EXPRESS VIA FOXCDX
 . LOCATE FOR COMMAND = 'dc_dot'

Files:

DCSTD.CH

See Also:

   dc_dblocate()
   dc_dbcontinue()
   CONTINUE


INTERP_LOCK_FILE

Lock the current file

LOCK FILE is used to lock the currently selected file before attempting to perform database operations that modify the data in mulitiple records.<br><br>

Syntax:

 LOCK FILE | ALL

Arguments:

 None.

Examples:

 . use customer
 . LOCK ALL
 . replace print_flag with .F. for print_flag
 . UNLOCK ALL

Files:

DCSTD.CH

See Also:

   dc_filock()


INTERP_LOCK_MAINT

Maintain the "Lock" definition database

LOCK EDIT is used to maintain a database of "Locks" which are put onto files, menu items, or fields when designing an application. This database, DCLOCKS.DBF, is used as a reference only and is not needed to establish locks on menu items or other locks. The database simply provides a handy picklist to choose a lock to put on an item. The database assigns names and codes to locks.

Syntax:

 LOCK EDIT

Examples:

 . LOCK EDIT

Files:

DCSTD.CH

See Also:

   dc_lockmaint()
   dc_usermaint()


INTERP_LOCK_REC

Lock the current record

LOCK is used to lock the currently selected record before attempting to replace field data.<br><br>

Syntax:

 LOCK

Arguments:

 None.

Examples:

 . USE COLLECT
 . GO 5
 . LOCK
 . COLLECT->condition := 'P'
 . UNLOCK

Files:

DCSTD.CH

See Also:

   dc_reclock()
   UNLOCK


INTERP_LOGIN

Login to application to establish user rights

LOGIN is used to log a user onto the system in the event that it is necessary to establish rights to menus, files, or specified fields. LOGIN calls the function DC_UserLogin().<br><br> The eXPress++ menu system, data-entry (editing) system, browsing system, and file system provide for establishing locks on menu items, fields and/or files. If these systems are used without first calling DC_Userlogin(), then the user will be given full rights. If however, DC_UserLogin() is called first, then the user will be given access to only those items in which the user has the exact key or a master key for each specified lock.<br><br> If the user logs on with the MASTER PASSWORD, then he/she is automatically established as a "programmer" and is given full access. The MASTER PASSWORD is hard-coded by a definition in DCUSER.CH. To change the MASTER PASSWORD you must redefine it in DCUSER.CH and then recompile _DCUSER.DBF and include the new _DCUSER.OBJ in your link-script.<br><br> User PASSWORDS are stored in the DCUSER.DBF database in encrypted form. Passwords may be assigned or changed only with the DC_USERMAINT() function or the USER EDIT command.<br><br> User KEYS are stored in the DCUSER.DBF database and may be assigned or changed only with the DC_USERMAINT() function or the USER EDIT command. Locks are placed on menu items or fields by entering a 3-character "lock" sequence when using the menu-designer and/or data-entry designer. A database of standard locks and their definitions may be maintained by DC_LOCKMAINT(). When assigning a user a set of "keys" they may be specific keys or "master" keys. A Master key is assigned by using wild-cards. For example, the Master Key "5****" will allow access to any lock starting with the number "5", whereas the Master Key "67***" will allow access to any lock with the number "67". Keys are stored in the USR_KEYS field and are separated by commas.<br><br> Example:<br><br> "1****,2****,3****,41***,42***,52231,6****"<br><br><br><br>

Syntax:

 LOGIN [USER <cUserID>] ;
    [PASSWORD <cPassword>]

Arguments:

USER <cUserID> is the User ID of the logging on user.  If this
parameter IS NOT passed and the PASSWORD <cPassword> parameter
IS passed, then the DCUSERS.DBF will be searched only for a
match to the <cPassword>.  If <cUserID> is passed and
<cPassword> is not passed, then the user will be prompted to
enter a password.  If neither <cUserID> or <cPassword> is
passed, then the user will be prompted for both a User ID
and a password.

Examples:

 . LOGIN USER LARRY PASSWORD BOOZER

Files:

DCSTD.CH

See Also:

   dc_userlogin()


INTERP_MENU_EDITOR

A Complex Pull-Down Menu Editor

MENU EDIT is a menu-designer system that will create complex pull-down menus. Menus are designed by entering information in a browse-style window that displays menu items and sub-menus in an easy-to-read "indented" format. The designed menu can be saved to an array, an array file, the data-dictionary, or to source-code which can be compiled and run by your application.<br><br> MENU EDIT creates menus that are passed as an array to the DC_MENUMAIN() (Text Mode Reader) or DC_MENUOSYS() (Gui Mode Reader) functions for execution. During the menu design process, the menu can be executed in a WYSIWIG fashion to provide instant feedback that the menu will function as it has been designed.<br><br> MENU EDIT supports all the features of DC_MENUMAIN() and DC_MENUOSYS() including sub-sub-menus, automatic mouse support, message boxes, help-codes, accelerator keys, code-blocks, and access keys. In addition, DC_MENUEDIT() supports conditional compiling of menu items to exclude key items at run-time based on a key list that is passed to DC_MENURUN() or DC_MENUCOMPILE() or based on a code block.<br><br>

Syntax:

 MENU EDIT [ <acMenu> ] ;
    [CREATE]

Arguments:

<acMenu> is the name of the menu or the menu contents. If
<acMenu> is a character string, it is a name of up to eight (8)
digits.  If <acMenu> is an array, it must conform to the
specifications of a menu array defined in the RETURNS section.
If a menu name is passed then the DCMENU.DBF menu dictionary
database will be searched and all menu items that match the
menu name be loaded into an array for editing. If a NIL is
passed, then a pick-list of all menus stored in the DCMENU.DBF
database will be displayed.  If none is chosen, then it will
be assumed that you wish to create a new menu.

CREATE will create a new menu.

Examples:

 /* -- Edit the Main Menu -- */
 MENU EDIT MAINMENU

Files:

DCSTD.CH

See Also:

   dc_menuedit()
   dc_menuload()


INTERP_MODI_STRU

Modify the structure of a database

MODIFY STRUCTURE is used to change the structure of the database in the current work area and restore all the data in the file or save the database to a new name.<br><br> You can add perform the following operations with a GUI dialog:<br><br> 1. Add a new field 2. Delete a field 3. Move a field 4. Rename a field 5. Replicate a set of new fields 6. Change the type of a field 7. Change the length of a field<br><br> All data in the former file will restored to the modified file except for any fields that were deleted.<br><br>

Syntax:

 MODIFY STRUCTURE [TO <cNewFileName>]

Arguments:

TO <cNewFileName> is the name to assign to the new modified file.
If no argument is given, then the new file name will be the
same as the original and the original file will be renamed to
the same name as the file alias with a .DBK extension.  If the
file contained at least one memo field, then the memo file
will be renamed to the same name as the file alias with the
.DTK extension.

Examples:

 . USE COLLECT
 . MODIFY STRUCTURE TO COLLECT2

Files:

DCSTD.CH

See Also:

   dc_modstru()
   dc_struupdate()


INTERP_OBJ_FILES

Establish the working directory for .OBJ files

SET ODIR is used to define the drive and directory to place .OBJ files when compiling .PRGs with the COMPILE | XPP command.<br><br>

Syntax:

SET ODIR TO <cObjDirectory>

Arguments:

<cObjDirectory> is the directory name to place .OBJ files.

Examples:

 . SET PDIR TO \MYAPPS\PRG
 . SET ODIR TO \MYAPPS\OBJ
 . XPP MYMENU
 . XPP MYPROCS

Files:

DCSTD.CH

See Also:


INTERP_ODOMETER

Set percentage update of progress odometer

SET ODPERCENT sets how often to update the progress indicator odometer when using DC_ODOMETER() or DC_ODBLOCK().<br><br>

Syntax:

 SET ODPERCENT TO <nPercent>

Arguments:

<nPercent> is a numeric value for the percentage of update
you want on the progress odometer.  If you have very large
files and want to see progress more often, then it is
recommended you lower this number from the default of 5
percent.

Examples:

 . SET ODPERCENT TO  1  // 1 percent
 . index on cust_nmbr to custnmbr

Files:

DCSTD.CH

See Also:

   dc_odometer()
   dc_odblock()


INTERP_PACK

Pack the current database

PACK is a high-level command that will pack the database in the currently selected work area. This function does not use the Clipper dbPack() function but instead packs the file as follows:<br><br> 1. Displays a progress odometer during the packing process. 2. Optimizes size of memo fields (removes dead space). 3. Creates a backup file.<br><br>

Syntax:

 PACK

Arguments:

 None.

Examples:

 . USE EXPRESS INDEX EXPRESS.CDX VIA FOXCDX
 . PACK

Files:

DCSTD.CH

See Also:

   dc_pack()


INTERP_PICK_DATABASE

Select a database from a picklist of open files

SELECT will pop-up a picklist of all work areas and display the alias and database file name open in each work area. It will also allow the user to select an unused work area to open a new database.<br><br> If arguments are passed, then SELECT functions identical to the Xbase++ SELECT command. If no arguments are passed, SELECT uses the DC_DbfSel() function to select or open a new database.<br><br>

Syntax:

 SELECT

Arguments:

 None.

Examples:

 . SELECT

Files:

DCSTD.CH

See Also:


INTERP_PROG_DICT

Maintain the DCPROG.DBF Program Dictionary File

PROGRAM MAINTENANCE is used to maintain a database catalog of programs for later interpreting with PROGRAM or DC_PROGRAM(). This system in intended for creating small programs that may be run from the dot-prompt, menus, data-entry validations, etc.<br><br> PROGRAM MAINTENANCE provides an editor, search routines, print routines, etc. <br><br> Programs are saved in a MEMO field in the DCPROG.DBF/.DBT file. These "interpreted" programs are not intended to replace compiled code but are instead a handy way of creating additional on-the-fly functions and procedures to give a data-driven system some extra convenience and functionality.<br><br>

Syntax:

 PROGRAM MAINTENANCE

Arguments:

 None.

Examples:

 . PROGRAM MAINT

Files:

DCSTD.CH

See Also:

   dc_progmaint()


INTERP_PROMPT_TYPE

Establish the type of prompt for the Dot-prompt

SET PROMPT is used to enable or disable the display of the directory prompt that is displayed before the dot on the command line or to establish a custom prompt.<br><br>

Syntax:

 DEFAULT will display the current setting of the SET DEFAULT
 directory.  This is the directory selected by the
 SET DEFAULT command or DC_SETT('DEFA') function.  Use this
 option if you  wish to see the default directory in which
 databases, indexes, form files, etc. will be opened and
 created.  If SET DEFAULT is empty, i.e, SET DEFAULT TO, then
 databases will be created in the current DOS directory.

 DOS will display the current selected DOS directory.   This
 is the directory selected by the CD command or DC_CHDIR()
 function.  Low-level file functions such as FOPEN(),
 DC_TXTOPEN() etc. will look in the DOS directory for files
 if no path is included in the file name.

 <expression> is any expression that returns any value.

Files:

DCSTD.CH

See Also:

   dc_dot()


INTERP_PURGE

Purge duplicate records from a database

PURGE is used to remove records from a database that have duplicates based on a test of specified fields. The purged records will be marked as *deleted* but will not actually be removed from the data file until the file is packed. This will allow you to BROWSE the file and monitor the purged information before completing the final reduction.<br><br> PURGE actually creates a temporary index file based on an expression that is passed or created from the pop-up index builder.<br><br> Purged records can be written to a new data file for recovery at any time.<br><br>

Syntax:

 PURGE ON <exp1> ;
       [TO <file>] ;
       [RETAIN <exp2> ;
       [MAX | MIN]] ;
       [FIELD <field>]

Arguments:

ON <exp1> is an expression of field names to use in determining
how to determine the duplication of records.  For example, if
you want to purge records that have duplication of information
in which LAST_NAME, FIRST_NAME and STREET are identical, then
use UPPER(LAST_NAME+FIRST_NAME+STREET) as the expression.

If an <expression> is not given then a window will appear with
a user prompt to enter an expression or to press ALT-F for the
index builder.  If ALT-F is pressed, a pick-list of fields will
appear to aid in building the expression.

TO <file> will create a new database that contains the purged
records.

RETAIN <exp2> is an expression that determines which record of
the set of duplicate records to retain (not mark for deletion).
The default is "RECNO()".  MAX will retain the maximum value.
MIN will retain the minimum value.  The default is MIN.

FIELD <field> is the name of an optional numeric field in the
database being purged. This field is used to write a number from
0 to N.  If there are no duplicates, then a 0 will be written to
the record.  If there ARE duplicates then a 1 will be written to
the RETAINED record and a number from 2 to N will be written to
each duplicate.

Notes:

PURGE will not actually remove duplicate records from the database, but will instead mark them for deletion. To complete a full purge of the duplicate records, you must PACK the database. If you wish you recall the deleted records after a purge, use the command RECALL ALL.

Examples:

 /* Purge all duplicate records that have an exact match
    for Last Name, First Name, Phone Number and Street.
    Retain the record that has the latest Mail Date */

 . USE MAILLIST
 . PURGE ON LAST+FIRST+PHONE+STREET RETAIN MAIL_DATE MAX
 . BROWSE
 . PACK

Files:

DCSTD.CH

See Also:

   dc_purge()


INTERP_RECALL

Recall record(s) that were previously marked for deletion

RECALL without arguments is used to recall the current record after it was previously marked for deletion. This command is a front-end to the Xbase++ dbRecall() function that automatically locks and unlocks the record to prevent a runtime error on shared databases. <br><br> RECALL with arguments works identical to the Xbase++ RECALL command except a progress odometer will display the number of records scanned and the number of records that were actually recalled.<br><br>

Syntax:

 RECALL [ <args> ]

Arguments:

 See the Xbase++ documentation for <args>.

Examples:

 . USE EXPRESS INDEX EXPRESS.CDX SHARED
 . GO 10
 . RECALL
 . RECALL WHILE RecNo() < 20

Files:

DCSTD.CH

See Also:

   dc_recall()
   DELETE


INTERP_REPLACE_VIRT

Replace the current record contents with Virtual record arra

REPLACE VIRTUAL will replace the contents of the current record with the data in the virtual record. This function will automatically handle the record locking, so it is not necessary to lock the record.<br><br>

Syntax:

 REPLACE WITH VIRTUAL

Arguments:

 None.

Examples:

 . USE COLLECT
 . GO 5
 . SAVE VIRTUAL
 . GO 6
 . REPLACE VIRTUAL

Files:

DCSTD.CH

See Also:

   dc_virtrepl()


INTERP_RESTORE_ARRAY

Restore a multidimensional array from a binary file

RESTORE ARRAY will create an multidimensional array from the contents of a binary file that was created with SAVE ARRAY.

Syntax:

 RESTORE ARRAY <aArray> [FROM <cFileName>]

Arguments:

<aArray> is the name of the variable to store the array contents.

FROM <cFileName> is the name of the binary file that was previously
created with SAVE ARRAY or DC_ASave().  If this argument is not
passed then a file named <aArray>.DCA will be the default.

Examples:

 . aDir := Directory()
 . SAVE ARRAY aDir
 . RESTORE ARRAY aDir
 . SAVE ARRAY aDir TO junk.ar
 . RESTORE ARRAY aDir FROM junk.ar

Files:

DCSTD.CH

See Also:

   dc_arestore()
   SAVE ARRAY


INTERP_RESTORE_WORK

Restore work areas

RESTORE DATA will reopen all databases, indexes and relations from the array created by SAVE DATA or DC_DataSave(). This function is handy when it is necessary to insure that database work areas are restored to their original condition after calling a routine that may close files, open files, select different indexes or clobber relations.<br><br>

Syntax:

 RESTORE DATA FROM <aWorkArea>

Arguments:

<aWorkArea> is a multidimensional array created by the SAVE DATA
command or DC_DataSave() function.

Examples:

 . USE EXPRESS ALIAS XDOC VIA FOXCDX INDEX EXPRESS
 . SET TAG TO COMMAND
 . SAVE DATA TO aWorkArea
 . CLOSE ALL
 . RESTORE DATA FROM aWorkArea

Files:

DCSTD.CH

See Also:

   dc_datarest()


INTERP_RUN_PROGRAM

Run a Program from the Program Dictionary

PROGRAM is used to load a program from the DCPROG.DBF program catalog database and execute the program using the interpreter or runtime compiler. Programs in the dictionary are pre-designated as "Interpreted" or "Compiled".<br><br> Interpreted programs may contain any command that can be intrepreted at the dot-prompt plus the same type of structural elements as standard Clipper programs such as DO..WHILE and FOR..NEXT loops, IF..ELSE, DO..CASE statements, PARAMETERS statement and RETURN value, however they cannot contain CLASS statements, FUNCTION statements, LOCALS or STATICS. If a program is designated to be Interpreted, the program is passed to the DC_INTERPRET() function.<br><br> Compiled programs may contain any type of code that can be compiled with the XPP.EXE compiler. IF a program is designated to be Compiled, the program is first compiled by the DC_COMPILE() function, then loaded into memory with the DC_OBJLOAD() function and executed.<br><br><br><br>

Syntax:

 PROGRAM [ <cProgName> ] ;
    [WITH <aParams>]

Arguments:

<cProgName> is the Tag Name of the program in the DCPROG.DBF
Program Catalog file.  If no parameter is passed, then a pick-
list of available programs will be displayed.  If an array
<aProgram> is passed then it must conform to the structure
of the array returned by DC_PROGLOAD() or interpreted
programs.

WITH <aParams> is a single-dimensional array of parameters to pass
to the program being interpreted.  There should be one element
in the array for each parameter included in the PARAMETERS
statement in the interpreted program.  If less parameters are
passed than specified in the PARAMETERS statement, the unpassed
parameters will be initialized to NIL.

Examples:

 . PROGRAM TEST WITH { Date(), Time() }

Files:

DCSTD.CH

See Also:

   dc_program()


INTERP_SAVE_VIRT

Save current record to Virtual record

SAVE VIRTUAL is used to save the contents of the current record to a virtual record. A virtual record is a file with the same prefix as the database alias and with the extension .DCV. The virtual record can then be used at any time to replace the contents of specified records in the same database by using the REPLACE WITH VIRTUAL, INSERT VIRTUAL or APPEND VIRTUAL commands.<br><br>

Syntax:

SAVE VIRTUAL

Arguments:

None

Examples:

 . USE MAILLIST
 . GO 2345
 . SAVE VIRTUAL
 . APPEND BLANK
 . REPLACE WITH VIRTUAL
 . GO 1000
 . INSERT VIRTUAL 10

Files:

DCSTD.CH

See Also:

   APPEND VIRTUAL
   DC_VirtSave()


INTERP_SAVE_WORK

Save info about all open workareas to an array

SAVE DATA will store all work area info to an array.<br><br> RESTORE DATA will reopen all databases, indexes and relations from the array created by SAVE DATA or DC_DataSave(). This function is handy when it is necessary to insure that database work areas are restored to their original condition after calling a routine that may close files, open files, select different indexes or clobber relations.<br><br>

Syntax:

 SAVE DATA TO <aWorkArea>

Arguments:

<aWorkArea> is the name of the variable to store the array
pointer.

Examples:

 . USE EXPRESS ALIAS XDOC VIA FOXCDX INDEX EXPRESS
 . SET TAG TO COMMAND
 . SAVE DATA TO aWorkArea
 . CLOSE ALL
 . RESTORE DATA FROM aWorkArea

Files:

DCSTD.CH

See Also:

   dc_datasave()


INTERP_SEARCH_DATA

Search all fields in a set of databases for a value

SEARCH is used to search all fields of specified work areas for matching text and list all occurences of found text.<br><br> The output can be sent to the screen, printer or a file and all occurrences where the text is found will be listed as follows:<br><br> File Record Field Text ----------- ------ ------------ --------------------------- CUSTOMER 123 PHONE 714-555-1212 MAILLIST 23567 PHONE_NUM (619)555-1212<br><br>

Syntax:

SEARCH [ <cFileName> ] ;
    [FOR <cText>] ;
    [TOPRINT ] ;
    [TOFILE <dest>]

Arguments:

<cFileName> is the name of the database to search.  If no path
is given then the current SET DEFAULT directory is assumed.  If
<cFileName> is "ALL", then all databases that match the
currently selected RDD will be searched.  If no argument is
passed then a GUI dialog will be displayed prompting for a
file name, text and output.

FOR <cText> is the text to search for.  This is a case
non-sensitive search and the first occurrence of the text in
each field will be listed.  If no argument is passed then a
GUI dialog will be displayed prompting for a file name, text
and output.

TOPRINT will send the report to the printer.  TOFILE <dest>
will send the report to the file <dest>.

Examples:

 // search CUSTOMER.DBF for occurrences of "O'BRIEN"
 // and display results on screen
 . SET RDD TO DBFNTX
 . SEARCH CUSTOMER FOR "O'BRIEN"

 // search CUSTOMER.DBF for occurrences of "O'BRIEN"
 // and copy results to file OBRIEN.TXT
 . SET RDD TO DBFNTX
 . SEARCH CUSTOMER FOR "O'BRIEN" TO FILE OBRIEN.TXT

 // search all .DBF's for occurences of "CLIPPER"
 . SET RDD TO DBFNTX
 . SEARCH ALL FOR CLIPPER

Files:

DCSTD.CH

See Also:

   dc_search()


INTERP_SEEK_SCOPEDREC

Seek a record in a set of Scoped Records

SEEK is used to SEEK a record in a group of "scoped" records. Scopes are set via the DC_SetScope() function. This functions identical to the Xbase++ dbSeek() function except if the record is not found or is outside the range of the scope, it behaves as follows:<br><br> 1. If the record is not found the record pointer is placed at Eof() and a .FALSE. is returned.<br><br> 2. If the record is found but the indexkey() value is less than the top scope, the record pointer is placed at the beginning record of the scope and a .FALSE. is returned.<br><br> 3. If the record is found but the indexkey() value is greater than the bottom scope, the record pointer is placed at the last record of the scope and a .FALSE. is returned.<br><br> 4. If the record is found and the indexkey() value is within the range of the top and bottom scope, the record pointer is placed at the found record and a .TRUE. is returned.<br><br> If no scope is set, then SEEK simply calls dbSeek().<br><br>

Syntax:

 SEEK <xValue>

Arguments:

<xValue> is any value of the same type as the index key for
the selected order.  If no argument is passed then a GUI dialog
will be displayed for entering a value.  See FIND and DC_Find()
for a description of this GUI dialog.

Examples:

 . USE EXPRESS VIA FOXCDX INDEX EXPRESS
 . SET SCOPE TOP TO 'DC_F'
 . SET SCOPE BOTTOM TO 'DC_H'
 . SEEK 'DC_G'
 . ? Eof()
.F.

Files:

DCSTD.CH

See Also:

   dc_dbseek()
   dc_find()
   HUNT
   FIND


INTERP_SET_COMMAND

Create a command to run a function or procedure

SET PROCEDURE adds command verbs to a table of commands for evaluating expressions from a single verb command. This is a handy method of creating quick commands to run functions or code blocks.<br><br>

Syntax:

 SET PROCEDURE TO <cCommandVerb>, <idExpression>

Arguments:

<cCommandVerb> is the name of the command you wish to use at
the dot prompt execute the procedure.

<idExpression> is the name of the procedure or function to
execute when the <cCommandVerb> is entered at the dot prompt.

Examples:

 . SET PROCEDURE TO CALLHOME, DIALOUT("714-555-1212")
 . CALLHOME
 . SET PROCEDURE TO HELLO, Eval({||MsgBox('Hello'),MsgBox('World')})
 . HELLO

Files:

DCSTD.CH

See Also:


INTERP_SET_EDIT

Pop up an editing screen for all SET environment variables

SET is used to invoke a GUI editor for observing or modifying the value of any SET value in the environment.<br><br> The SET environment is the complete set of standard Xbase++ SETs such as SET EPOCH, SET DEFAULT, etc. and the additional eXPress++ SETs such as SET ODIR, SET PROMPT, etc.<br><br>

Syntax:

 SET [ <cSetName> ]

Arguments:

<cSetName> is the name of the SET environment variable to
edit.  If this parameter is not passed, then a picklist of all
environment variables will be displayed for editing.

Examples:

 . SET
 . SET DEFAULT
 . SET ODIR

Files:

DCSTD.CH

See Also:

   dc_setedit()


INTERP_SET_ENVIR

Restore the SET environment from a file

RESTORE SET is used to restore the values of all Xbase++ and eXPress++ environment variables from a file previously created by SAVE SET.<br><br> The SET environment is the complete set of standard Xbase++ SETs such as SET EPOCH, SET DEFAULT, etc. and the additional eXPress++ SETs such as SET ODIR, SET PROMPT, etc.<br><br>

Syntax:

 RESTORE SET FROM <cFileName>

Arguments:

<cFileName> is the name of the file previously created by
DC_SetSave() or SAVE SET.  If no extension is given then the
extension .DCA will be added.

Examples:

 . SAVE SET TO MYFILE.SET
 . DoSomethingThatChangesEnvironment()
 . RESTORE SET FROM MYFILE.SET

Files:

DCSTD.CH

See Also:

   dc_setrest()
   dc_setsave()


INTERP_SET_GUI_TEXT

Set the Dialogue mode to GUI or TEXT

SET GUI or GUI is used to set Text or Gui mode for Dual-Mode Functions. The eXPress++ library contains a variety of functions which operate in "Dual-Mode". When GUI mode is ON, the function uses a GUI dialogue based on Xbase Parts. When the GUI mode is OFF the function works in standard text-mode.<br><br>

Syntax:

 SET GUI ON | OFF

Arguments:

SET GUI ON will cause eXPress++ to process Dual-Mode functions as
a GUI dialogue.  SET GUI OFF will cause eXPress++ to process all
Dual-Mode functions as a TEXT dialogue.

Examples:

 . SET GUI ON
 . DC_PopCalc()  // pop up a GUI based calculator
 . SET GUI OFF
 . DC_PopCalc()  // pop up a Text based calculator

Files:

DCSTD.CH

See Also:

   dc_gui()


INTERP_SET_PROC

Create a command to run a batch file

SET BATCH adds command verbs to a table of commands for processing batch (.DCB) files from a single verb command. This is a handy method of creating quick commands to run batch files.<br><br>

Syntax:

SET BATCH TO <cCommandVerb>, <xcBatchFile>

Arguments:

<cCommandVerb> is the name of the command you wish to use at
the dot prompt execute the batch file.

<xcBatchFile> is the name of the batch file to run when the
<cCommand Verb> is entered at the dot prompt.  If no extension
is given, then .DCB is assumed.

Examples:

 // Batch file MYMOVE.DCB contains the following commands:
 //   COPY FILE %1 %2
 //   ERASE %1

 . SET BATCH TO MOVE, MYMOVE.DCB
 . MOVE \DCLIP\MYFILE.TXT \JUNK

Files:

DCSTD.CH

See Also:


INTERP_SET_SAVE

Save the SET environment to a file

SAVE SET is used to save the values of all Xbase++ and eXPress++ environment variables to a file to be later restored by RESTORE SET or DC_SetRest().<br><br> The SET environment is the complete set of standard Xbase++ SETs such as SET EPOCH, SET DEFAULT, etc. and the additional eXPress++ SETs such as SET ODIR, SET PROMPT, etc.<br><br>

Syntax:

 SAVE SET TO <cFileName>

Arguments:

<cFileName> is the name of the file to create.  If no extension
is given then the extension .DCA will be added.

Examples:

 . SAVE SET TO MYFILE.SET

Files:

DCSTD.CH

See Also:

   dc_setsave()
   dc_setrest()


INTERP_SOURCE_EDITOR

Establish the default source code editor

SET EDITOR is used to define the name and path of the default editor you wish to use when using the IDE features of eXPress++, such as the EDIT FILE command and re-editing after compiler errors.

Syntax:

 SET EDITOR TO <cFileName>

Arguments:

<cFileName> is the name of the editor .COM, .BAT or .EXE
file to run when using the EDIT command.

Examples:

 . SET EDITOR TO C:\EXPRESS\UTIL\ME2.BAT

Files:

DCSTD.CH

See Also:


INTERP_STACK_SIZE

Set the size of the Dot-prompt command stack

SET DOTSTACK is used to increase the length of the Dot-Prompt command stack array to a value greater than the default value of 100 commands. This is desirable in the event that it is necessary to save and restore more than the last 100 commands with the HISTORY=<file> command in your DCLIP.SYS.

Syntax:

 SET DOTSTACK TO <nSize>

Arguments:

<nSize> is a number from 100 to 4000.

Examples:

 SET DOTSTACK TO 500

Files:

DCSTD.CH

See Also:


INTERP_WORKING_DIR

Establish the working directory for .PRG files

SET PDIR is used to define the drive and directory to search for .PRG files when searching for source code using such commands as EDIT FILE, COMPILE, etc.

Syntax:

 SET PDIR TO <cPrgDirectory>

Arguments:

<cPrgDirectory> is the directory containing the source .PRG
files.

Examples:

 . SET PDIR TO \MYAPPS\PRG
 . SET ODIR TO \MYAPPS\OBJ
 . XPP MYMENU
 . XPP MYPROCS

Files:

DCSTD.CH

See Also:

   dc_editprg()


SET STATUS

Toggle display of GUI Status Window

SET STATUS is used to enable or disable the display of the GUI status window at the top of the display. The status window provides important information about the current work area.<br><br>

Syntax:

SET STATUS ON | OFF | <lToggle>

Arguments:

ON will enable display of the status line.

OFF will disable the status line.

<lToggle> if .T. is equivalent to ON, if .F. is equivalent to
OFF.

Examples:

 . SET STATUS ON
 . SET STATUS OFF

Files:

DCSTD.CH

See Also:

   dc_dot()


SET TALK

Toggle display of pre-processed output

SET TALK is used to enable or disable the echoing of the pre- processed output to the console. All commands entered at the dot- prompt are passed through the pre-processor and converted to a function or set of functions to be evaluated in sequence.<br><br> When debugging #command, #translate or #define statements in .CH files previously loaded with the #include <mycommands> in your DCCUSTOM.CH file. SET TALK ON will show the results of the translation.<br><br>

Syntax:

SET TALK ON | OFF | <lToggle>

Arguments:

ON will enable the echoing of preprocessed output to the
console.

OFF will disable echoing of preprocessed output (default).

<lToggle> if .T. is equivalent to ON, if .F. is equivalent to
OFF.

Examples:

 . #TRANSLATE PHONE <number> => DIALOUT(<(number)>)
 . #DEFINE HOME 714-555-1212
 . SET TALK ON
 . PHONE HOME

 DIALOUT("714-555-1212")

Files:

DCSTD.CH


SET USEEXCLDATA

Force Exclusive use of application databases

SET USEEXCLDATA is used to override any default settings for opening databases and insure that they are always opened in EXCLUSIVE mode only. This flag should be used when using eXPress++ in "design" mode. Design mode means that the user or programmer is designing Browse and Data-Entry screens and/or Field Definitions. When adding or changing database fields or packing files, they must be opened in "Exclusive" mode.

Syntax:

SET USEEXCLDATA on | OFF

Arguments:

ON will force databases that are opened by the eXPress++ USE
command, DC_UseArea() function, DC_WorkRestore(), DC_Dbfile(),
or any other eXPress++ function or command that opens databases
to be opened EXCLUSIVE regardless of how parameters are
passed to these functions or the setting of the SET EXCLUSIVE
system flag.

OFF will insure that databases are opened by the default
method for each function.

Notes:

When designing a system it is recommended that you place the following commands in your DCLIP.SYS file:

USEEXCLDATA=ON USEEXCLDICT=OFF

or type the following commands at the dot prompt:

SET USEEXCLDATA ON SET USEEXCLDICT OFF

Files:

DCSTD.CH

See Also:


SET XPPOPT

Set the default Compiler switches

SET XPPOPT TO is used to establish a set of default options to be used by the XPP.EXE compiler when the COMPILE or XPP command is used at the dot-prompt to compile programs.<br><br>

Syntax:

SET XPPOPT TO <compiler options>

Arguments:

<compiler options> is a list of options you want to pass to the
Xpp.exe compiler.

Examples:

 . SET XPPOPT TO /i\ALASKA\XPPW32\INCLUDE /n /w /b /dDEBUGMODE
 . XPP MYAPP

Files:

DCSTD.CH

See Also:

   SET XPPPATH


SET XPPPATH

Set the directory when the Compiler resides

SET XPPPATH is used to define the directory in which the XPP.EXE compiler resides for eXPress++ compiler operations.<br><br>

Syntax:

SET XPPPATH TO <directory>

Arguments:

<directory> is the name of the directory in which the XPP.EXE
compiler exists.  If XPP.EXE is already in your operating
system environment path, then SET XPPPATH is not necessary.

Examples:

 . SET XPPPATH TO \ALASKA\XPPW32\BIN
 . XPP MYAPP

Files:

DCSTD.CH

See Also:

   SET XPPOPT


SET_SCOPE

Set a scoping value for the current work area

SET SCOPE is used to set a SCOPE TOP and SCOPE BOTTOM value for establishing a "scoping range" for a work area. The eXPress++ browsing and editing systems use SET SCOPE and DC_SETSCOPE() to store the scoping range when browsing and editing records. When a scoping range is set, only the records that fall within the range will appear in the browse or edit screens. <br><br>

Syntax:

 SET SCOPE [TOP | BOTTOM] TO [<xValue1>] [,<xValue2>]

Arguments:

If the TOP clause is used then the SCOPE TOP is set to <xValue1>.
If the BOTTOM clause is used then the SCOPE BOTTOM is set to <xValue1>.

If neither the TOP or BOTTOM clause are used then both the <xValue1>
(TOP) and <xValue2> (BOTTOM) arguments are required.

<xValue1> and <xValue2> are values to set.  This must be a value
that matches the current index key.

Notes:

With the exception of COMIX and Advantage Server, DC_SETSCOPE() does not establish the scoping range at the DBE-layer level, but instead stores the scoping information in dbCargo() as an array.

The scoping information is retrieved by record navigation functions such as DC_DBGOTOP(), DC_DBGOBOTTOM() and DC_DBSKIP().

Examples:

 . USE EXPRESS ALIAS XDOC INDEX EXPRESS.CDX
 . SET ORDER TO 'COMMAND'
 . SET SCOPE TO 'A','C'  // set top to 'A' and bottom to 'B'
 . SET SCOPE TOP TO 'A'  // set top to 'A'
 . SET SCOPE BOTTOM TO 'B'  // set bottom to 'B'
 . SET SCOPE TO // clear top and bottom scopes
 . SET SCOPE TO 'H'  // set top and bottom to 'H'
 . SET SCOPE TOP TO  // clear top scope
 . SET SCOPE BOTTOM TO // clear bottom scope

Files:

DCSTD.CH

See Also:

   dc_setscope()
   dc_clrscope()
   CLEAR SCOPE


SKIP

Skip records in a set of Scoped Records

SKIP is used to SKIP <n> records in a group of "scoped" records. Scopes are set via the DC_SetScope() function.<br><br> If a scope is not set, then SKIP simply calls dbSkip().<br><br>

Syntax:

 SKIP [ <nRecords> ] [ALIAS <alias>]

Arguments:

<nRecords> is the number of records to skip.  Default is 1.

ALIAS <cAlias> is the alias of the workarea to skip.

Examples:

 . USE EXPRESS INDEX EXPRESS.CDX
 . SET ORDER TO 'COMMAND'
 . SET SCOPE TOP TO 'C'
 . SET SCOPE BOTTOM TO 'E'
 . GO TOP
 . SKIP

Files:

DCSTD.CH

See Also:

   dc_dbskip()


STACK

Display the callstack and optionally edit the source

STACK is used to display a GUI dialog listing the current call stack and line numbers.<br><br> Clicking on an item in the list will scan the list of .OBJs in the ODIR path to find the source of the function. If the same named function exists in more than one .OBJ, then all .OBJs will be listed. Clicking on the selected .OBJ will call the default editor and pass the name and line number of the selected source file to editor for editing.<br><br>

Syntax:

 STACK

Arguments:

 None.

Examples:

 . STACK

Files:

DCSTD.CH

See Also:

   dc_callstack()


SUM

Sum numeric fields in selected database

SUM is used to sum numeric fields in the currently selected database based on a set of conditions. This command functions identical to the Xbase++ SUM command with the exception that a progress bar is displayed during the summing and the number of records actually summed is displayed.<br><br> If no arguments are given, then SUM uses the DC_Sum() function to display a GUI dialog for selecting fields and options.<br><br>

Syntax:

 SUM [ <args> ]

Arguments:

 See the Xbase++ documentation for details about <args>.

Examples:

 . USE COLLECT
 . SUM orig_price TO nPrice
 . SUM

Files:

DCSTD.CH

See Also:

   dc_sum()


TAG

Build or add to a Record Tag Array

TAG is used to add or remove record numbers from an array of record numbers that can be used with all database commands for performing database operations on records that are "tagged". <br><br> TAG will first check for a logical field in the database named "TAG" and will operate on this field. If this field does not exist, it will operate on a PUBLIC array named DCTAGS.<br><br> A manifest symbol named TAGGED may be used in any expression at the dot-prompt. This symbol is automatically translated to DC_TAGGED() which is the function used to test whether or not a record has been tagged. This allows for simple use of the tagging system by easy-to-enter commands.<br><br>

Syntax:

 TAG [TO <aTags>] ;
     [CLEAR] ;
     [ FOR <for> ] ;
     [ WHILE <while> ] ;
     [ NEXT <n> ] ;
     [ ALL ] ;
     [ REST ] ;
     [ RECORD <rec> ]

Returns:

 A pointer to an array of tagged numbers.

Arguments:

CLEAR will remove record numbers from the tag array that
meet the specified conditions, otherwise records will be
added.

TO <aTags> is an existing array of record numbers which will
display the TAG marker in the browse display.  If no
argument is given then the public DCTAGS array will be
used.

The following clauses follow the conventions for database commands
documented in the Xbase++ help file:

FOR <for>
WHILE <while>
NEXT <n>
ALL
REST
RECORD <rec>

Notes:

CAUTION: The eXPress++ tagging system is designed for ad-hoc tagging of records using simple menu selection and database commands. You will notice a gradual speed detioration as you add more records to the tag array when browsing. This is because the DC_TAGGED() function must scan more records in the array. It is recommend that you refrain from tagging more than 1000 records or you may experience unacceptable slowness during browsing.

If you need a tagging system that will support a much larger number of records, it is recommended that you add a TAG (logical) field to your database.

Examples:

  . select customer
  . TAG CLEAR ALL
  . go 113
  . ? TAGGED
 .F.
  . TAG
  . ? TAGGED
 .T.
  . TAG CLEAR
  . ? TAGGED
 .F.
  . TAG FOR balanceɬ
  . TAG FOR zip='92001'
  . TAG CLEAR FOR balance򒮨
  . count for TAGGED
  . label form customer for TAGGED to print

Files:

DCSTD.CH

See Also:

   dc_rectag()


TAG_CLEAR

Clear the Record Tag Array

TAG CLEAR will clear the current record or all tags in the public DCTAGS array for the current work area.<br><br><br><br>

Syntax:

 TAG CLEAR [ALL]

Arguments:

ALL will clear all tags.  If this clause is not used, only
the tag for the current record will be cleared.

Notes:

CAUTION: The eXPress++ tagging system is designed for ad-hoc tagging of records using simple menu selection and database commands. You will notice a gradual speed detioration as you add more records to the tag array when browsing. This is because the DC_TAGGED() function must scan more records in the array. It is recommend that you refrain from tagging more than 1000 records or you may experience unacceptable slowness during browsing.

If you need a tagging system that will support a much larger number of records, it is recommended that you add a TAG (logical) field to your database.

Examples:

 . use customer
 . GO 10
 . TAG
 . GO 20
 . TAG
 . TAG CLEAR ALL

Files:

DCSTD.CH

See Also:

   dc_rectagclear()
   dc_rectag()
   TAG


UNLOCK

Unlock the current record

UNLOCK is used to unlock a record after it has been locked with LOCK, DC_RecLock(), Rlock() or dbrLock().<br><br>

Syntax:

 UNLOCK

Arguments:

 None.

Examples:

 . USE COLLECT
 . GO 5
 . LOCK
 . COLLECT->condition := 'P'
 . UNLOCK

Files:

DCSTD.CH

See Also:


USE

Open a database file in a work area

USE is similar to the Xbase++ USE command and can be used as a replacement for opening databases. This command tests the validity of a database and it's associated memo file (if it exists) before attempting to open it to prevent common errors. Working with different database drivers can make it difficult to determine the cause of an open error. This command is designed to test a database to make sure it is a proper type. Parameters passed to USE are identical to the Xbase++ USE command so this command can be used as a replacement.

Syntax:

 USE <db> ;
     [FOX>] ;
     [VIA <cDbe>] ;
     [ALIAS <cAlias>] ;
     [NEW] ;
     [EXCLUSIVE] ;
     [SHARED] ;
     [READONLY] ;
     [INDEX <list,...>] ;
     [ALTERNATE <cAltDbe>]

Arguments:

NEW will open the database in a new work area. If this clause
is not used current work area will be used.

VIA <cDbe> is the DBE to use.  If no argument is passed, then
the <cAltDbe> will be used followed by the current DBE.

FOX is an alternative to the VIA <cDbe> clause.  This clause will
set FOXCDX as the dbe.

<cDatabase> is the name of the file to open.  If no drive and
directory is included then the file must exist in the SET
DEFAULT directory or SET PATH directory.

SHARED will open the database in SHARED mode, otherwise it will
be opened in EXCLUSIVE mode.

READONLY will open the database for Read operations only.

<cAlias> is the ALIAS to assign to the work area.  If no
argument is passed then the prefix of the database name will
be used as the alias.

INDEX <list> is a list of associated indexes to open.

ALTERNATE <cAltDbe> is an alternate DBE to use if the database
cannot be opened by the primary <cDbe> driver.

Examples:

 . USE EXPRESS FOX INDEX EXPRESS.CDX

Files:

DCSTD.CH

See Also:

   dc_usearea()


USER_EDIT

Maintain the DCUSERS.DBF User Database

USER EDIT is used to maintain the DCUSER.DBF database for establishing User ID's, Names, Passwords, Access Keys, etc. <br><br>

Syntax:

 USER EDIT [ <cUserID> ]

Arguments:

If the <cUserID> argument is passed, then the record that
contains the USR_ID matching <cUserID> will be edited,
otherwise all records will be available for browsing and
editing.

Examples:

 . USER EDIT

Files:

DCSTD.CH

See Also:

   dc_usermaint()


UTIL

A menu of database utilities

UTIL provides a set of general-purpose database utilities to perform menu-driven, complex database operations on the currently selected work area. Menu Selections --------------------- Create Database Display Structure Modify Structure Copy Structure Append Records Copy Records Import a Data File Replace Data Copy Fields Delete Records Recall Records Sort Database Join with Database Count Records Sum Data Fields Average Data Fields Disk Directory Insert Blank Record(s) Pack DataBase Zap Database Import/eXport Memos Purge Duplicate Records<br><br>

Syntax:

 UTIL

Examples:

 . USE COLLECT
 . UTIL

Files:

DCSTD.CH

See Also:

   DC_Util()


WHERE SOURCE

Display a list of .OBJ/.PRG files containing PUBLIC proc

WHERE SOURCE is used to display a list of .OBJ files and the location of the original source that contain a specified PUBLIC procedure.

Syntax:

 WHERE SOURCE <cProc>

Arguments:

<cProc> is the name of the PUBLIC procedure to find.

Notes:

This function assumes that the source file has the same name as the obj file except with the .PRG extension. This function is needed when it is not known which directory the source resides.

Examples:

 . WHERE SOURCE MAIN

Files:

DCSTD.CH

See Also:

   dc_objsourcelist()


WHERE_PUBLIC

List .OBJ(s) that contain public function

WHERE PUBLIC is used to scan a set of .OBJ files and list the names of all .OBJs that contain a PUBLIC declaration of a specified function.<br><br> A file named DCPUBLIC.TXT will be created using the Xbase++ XPPFILT.EXE utility program. This file will contain a listing of all public functions in all .OBJs.<br><br>

Syntax:

 WHERE PUBLIC [ <cProc> ]

Arguments:

<cProc> is the name of the procedure/function to find.
If this argument is empty, a GUI dialog will be displayed to
prompt the user for a procedure name.

Notes:

All .OBJs in the search directory(s) established by the SET ODIR (eXPress++) environment variable. If this environment variable is empty, then the search path is established by the operating system SET OBJ environment variable.

Examples:

 . SET ODIR TO C:\TEST;F:\TEST
 . WHERE PUBLIC TEST

Files:

DCSTD.CH

See Also:

   dc_objpublic()


ZAP

Zap the database

ZAP is a front end to the Xbase++ dbZap() function that tests if a file is open exclusive and then prompts the user to reopen it exclusive before Zapping the file. In either case, the user is given the option of cancelling the operation.<br><br>

Syntax:

 ZAP

Arguments:

 None.

Examples:

 . USE COLLECT
 . ZAP

Files:

DCSTD.CH

See Also:

   dc_zap()


DBU

A Gui Database Management Utility

DBU is a database management utility that can be used to edit databases using any DBE including ADSDBE and ODBCDBE. DBU is an MDI-based dialog that contains a status window at the top of the dialog. This status window displays information about the currently selected work area and also contain some pushbuttons to popup further status windows.<br><br>A menu at the top of the dialog provides a complete set of database utilities, searching features and printing features. It also allows for an MDI child browse/edit window to be created for each open work area. When a browse/edit window is given focus with the mouse, the work area of that window is selected and the status of the selected work area is displayed at the top of the dialog window.<br><br>All MDI child windows are opened in the same thread as the parent window. <br><br>

Syntax:

DBU [ <args> ]

Arguments:

<args>
<arg1> thru <arg15> may be any of the following arguments:

/an - Load ADSDBE driver (.NTX/.DBT support)
/ac - Load ADSDBE driver (.CDX/.IDX/.FPT support)
/dbe:<default dbe name>
/tbl:<database name>
/ind:<index list (separated by commas)
/odbc - Load ODBC driver
/dsn:<data source name> - ODBC (use a + for each space in name)
/uid:<user id> - ODBC
/pwd:<password> - ODBC
/dbq:<database name> - ODBC
/dll:<dllname> - Load a dynamic link library
/srv:<server name or drive letter> - ADSDBE
/obj:<objfilename> - Load an .OBJ file
/proc:<procedure> - Run a procedure ( with parameters)

Examples:

DBU /odbc, /dsn:dBASE+Files, /adsntx

Files:

DCSTD.CH

See Also:

   dc_dot()
   dc_dbu()


OVERVIEW_DUAL_FUNC

Dual-Mode Functions

DUAL-Mode functions have been designed to work in either TEXT mode or GUI mode. Text mode is selected by calling DC_GUI(.f.) and GUI mode is selected by calling DC_GUI(.t.).<br><br> Functions in the DCLIPX.DLL dynamic-link library all start with the prefix DC_. The DCLIPX.DLL file is one of the libraries that are included with the dCLIP++ Application Development System, and your eXPress++ system is fully compatible with dCLIP++ in the event that at some time you wish to upgrade and utilize the dCLIP++ design tools. 


OVERVIEW_GENERAL

General Functions

General functions are those which have been designed to work identically in either TEXT mode or GUI mode. These functions do not create any output to the screen in either mode, therefore they can be used freely without regard to the screen mode, DC_GUI().<br><br> Functions in the DCLIPX.DLL dynamic-link library all start with the prefix DC_. The DCLIPX.DLL file is one of the libraries that are included with the dCLIP++ Application Development System, and your eXPress++ system is fully compatible with dCLIP++ in the event that at some time you wish to upgrade and utilize the dCLIP++ design tools. 


OVERVIEW_GUI_FUNC

GUI Functions/Classes

GUI functions are designed to work only in GUI mode. When any of these functions are used they ignore the setting of the DC_Gui() flag.<br><br> 


OVERVIEW_TEXT_FUNC

Text Mode Functions/Classes

Text-Mode functions are designed to work only in TEXT mode. When any of these functions are used they ignore the setting of the DC_Gui() flag and require that the SetAppWindow() be a CRT window (XbpCrt Class).<br><br> 


dc_excel2workarea()

Add data to a workarea from an Excel file.

DC_Excel2WorkArea() will add records to the currently selected workarea from the contents of an Excel file.

Syntax:

DC_Excel2WorkArea( <cExcelFile> ) -> lStatus

Returns:

A logical .T. if the data was added successfully.

Arguments:

<cExcelFile> is the name of the .XLS file (including full path).

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_excel2array()
   dc_workarea2excel()


dc_dbrecord()

Create a Database Record Object

DC_DbRecord() is a class that is used to create a data object for storing a database record.<br><br>The record object is created from a dynamic class which will have the name DATA_<alias>.<br><br>Each field name in <alias> will be added to the object as an iVar.<br><br>Two additional iVars are created:<br><br>RECORD_NUMBER - A numeric container for the current record number that is set when DC_DbScatter() is used.<br><br>RECORD_DELETED - A logical container for the Deleted() flag is set when DC_DbScatter() is used.<br><br>

Syntax:

DC_DbRecord():new() -> <oRecord>

Returns:

A record object created from the currently used database.

Arguments:

None.

Examples:

FUNCTION XTest()

LOCAL oRecord

USE COLLECT

oRecord := COLLECT->(DC_DbRecord():new())
COLLECT->(DC_DbScatter(oRecord))

@ 1,1 DCSAY 'Description' GET oRecord:descript
@ 2,1 DCSAY 'Type' GET oRecord:type
@ 3,1 DCSAY 'Sub-Type' GET oRecord:subtype

DCREAD GUI

COLLECT->(DC_DbGather(oRecord))

RETURN nil

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_dbscatter()
   dc_dbgather()
   dc_dbrecordcompare()
   dc_dbrecordcopy()


dc_abigelem()

Return element of longest string in an array

DC_ABIGELEM() will return the element number of the longest string in a single-dimensional array.<br><br>

Syntax:

 DC_ABigElem ( <aArray>, ;
               [@<nLength>] ) -> nElement

Returns:

 A number equivalent to the element of the array with the
 longest string.

Arguments:

<aArray> is the name of any single-dimensional array that is
fill with character strings.

@<nLength> is the name of a variable to place the length
of the item returned.

Examples:

 . nLength := 0
 . aTest := { 'abc','abcdef','abcde','abcd' }
 . ? DC_ABIGELEM( aTest, @nLength )
 2
 . ? nLength
 6

Files:

_DCARRAY.PRG, DCLIP1.DLL


dc_achoice()

A Dual-Mode replacement for ACHOICE()

DC_ACHOICE() is a Dual-mode replacement for AChoice(). When the GUI flag is ON, DC_ACHOICE() functions similiar to AChoice() except that it is displayed in GUI mode. When the GUI flag is OFF, DC_ACHOICE() functions identical to ACHOICE() except it is also activated by a mouse. The left button of the mouse is used to select the item in the window. The right button or double-clicking works identical to the ENTER key.<br><br> In TEXT mode, Hot keys can be activated by passing an array of screen coordinates (mouse-buttons) and key definitions.<br><br> In TEXT mode, an options array is used to define scroll-bars, colors, exit options, title, drag options, etc.<br><br> An optional array of Help-Codes may be passed for context- specific help on any selected item with the F1 key.

Syntax:

DC_AChoice ( <nTop>, <nLeft>, <nBottom>, <nRight>, ;
             <aMenuItems>, ;
             [<aSelItems>], ;
             [<cUserFunc> | <bUserFunc>], ;
             [<nInitialItem>], ;
             [<nWindowRow>], ;
             [<aButtons>], ;
             [<aOptions>], ;
             [<aHelpCodes>], ;
             [<aMenu>], ;
             [<lAttachMenu>] ) -> nPosition

Arguments:

<nTop>, <nLeft>, <nBottom>, <nRight> are the screen
coordinates.

<aMenuItems> is an array of character strings to include
in the pick-list.

<aSelItems> is an array of logical values.  There is one
element in this optional array for each element in
<aMenuItems>.  Each element in <aSelItems> that is a
.TRUE. will make the item in the window a "selectable"
item, otherwise it will be a non-selectable item and will
be displayed in "grayed" form.

<cUserFunc> | <bUserFunc> is the name of an optional User-Defined
function to call on exception keystrokes.  See the Clipper
documentation of ACHOICE() for more information on how to use
a UDF.  If the parameter is passed as a character string then
the function must be a PUBLIC, not STATIC function.

<nInitialItem> is the item to high-light in the window on
startup.

<nWindowRow> is the item to display as the first item in
the pick-list.

<aButtons> is an array of mouse-keys that conforms to the
specification for DC_MOUSEKEY().   See DC_MOUSEKEY() for
more information.

<aOptions> is a multi-dimensional array of the following
options:

Element  Type   Description
-------  ----   ----------------------------------------------
  [1]     L     If .TRUE. will display a scrollbar and box
                around the menu items.
  [2]     A     A sub-array of colors to use if element [1] is
                .FALSE.  If passed as a NIL then the Clipper
                default colors will be used.

                Element  Type  Description
               -------  ----  ----------------------------
                 [1]       C   Menu items color
                 [2]       C   Select bar color
                 [3]       C   Frame/scrollbar color
                 [4]       C   Spare
                 [5]       C   Unselectable items color

  [3]     C     Title on top of box.  Default is none.
  [4]     L     If .TRUE. then the operator will be allowed to
                drag the box with the mouse. Default is .FALSE.
  [5]     L     If .TRUE. then the display will be restored
                upon exit, otherwise it will remain.
  [6]     L     If .TRUE. then the frame, scroll-bar and title
                will be painted, otherwise only the items will
                be painted.
  [7]     L     If .TRUE. then after painting the scroll-bar,
                items and frame, DC_ACHOICE() will exit without
                waiting for a key or mouse-click.

<aHelpCodes> is an array of character string HELP CODES.
There is one element in this optional array for each element in
<aMenuItems>.  The HELP CODE will be passed on to the
DC_HelpF1() function for context-specific help if the operator
presses F1 on a selected item.

<aMenu> is an array defining a Top-Bar/Pull-Down menu. This
array must conform to the specification for the array passed
to the DC_MENUMAIN() function.   This Top-Bar menu will be
painted at the screen coordinates defined in the menu if
<lAttachMenu> is .FALSE. or directly attached to the top of
the pick-list window if <lAttachMenu> is .FALSE. (default).
The menu will be energized if the operator presses a key
matching one of the hightlighted characters in the menu, or
if the mouse is clicked on one of the top-bar menu items.
The menu array must contain code-blocks for each menu item
to execute functions based on the menu selection.  See
DC_MENUMAIN() for more information.

Examples:

 local nChoice
 local aButtons := { { 17,13,17,18,'C'},;
                     { 18,13,18,18,'D'},;
                     { 19,13,19,18,'M'} }
 local aDir := directory()
 set key asc('C') to myfunc
 set key asc('D') to myfunc
 set key asc('M') to myfunc
 cls
 @5,10 to 20,30
 @16,11 to 16,29
 @17,13 say 'Copy'
 @18,13 say 'Delete'
 @19,13 say 'Move'
 aDir := dc_aconvert( aDir )
 nChoice := DC_ACHOICE( 6,11,15,29,aDir[1],,,,,aButtons )
 set key asc('C') to
 set key asc('D') to
 set key asc('M') to
 return

 function myfunc

 @ 22,10 say ''
 do case
   case lastkey() = asc('C')
     ?? 'C button pressed'
   case lastkey() = asc('D')
     ?? 'D button pressed'
   case lastkey() = asc('M')
     ?? 'M button pressed'
 endcase
 return nil

Files:

_DCACHOI.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_dbchoice()
   dc_readapick()
   dc_apick()


dc_acompare()

Compare two arrays

DC_ACOMPARE() is used to test the contents of two arrays to determine if they are identical.

Syntax:

DC_ACompare ( <aArray1>, ;
              <aArray2> ) -> lStatus

Returns:

 A logical .TRUE. if the arrays are identical, .FALSE. otherwise.

Arguments:

<aArray1> and <aArray2> are the arrays to compare.

Examples:

  PROCEDURE Xtest()

  LOCAL aArray1, aArray2, aArray3

  aArray1 := { 1,2,3 }
  aArray2 := { '1',2,3, }
  aArray3 := { 1,2,3 }

  DC_Gui(.t.)

  DC_MsgBox( { 'Is aArray1 equal to aArray2?', ;
               '',;
               DC_ACOMPARE(aArray1,aArray2) } )

  DC_MsgBox( { 'Is aArray1 equal to aArray3?', ;
               '',;
               DC_ACOMPARE(aArray1,aArray3) } )

  RETURN

Files:

_DCARRAY.PRG/.OBJ, DCLIPX.LIB


dc_aconvert()

Convert a Ragged array to a Parallel array and vice-versa

DC_ACONVERT() is used to changed the format of a symmetrical array from "Ragged" to "Parallel" or vice-versa. This function is handy when information in an array may not be stored in a required format. For example, it is not easy to perform "pick-list" operations from "Ragged" arrays or to AEVAL() "Parallel" arrays.

Syntax:

DC_AConvert ( <aInput> ) -> aOutput

Returns:

 An array whose elements contain the same information as the
 input array but are in "inverted" order.

Arguments:

<aInput> is a Parallel Symmetrical array or Ragged Symmetrical
array.

Example of a "Parallel Symmetrical array":

                  Type  Contents

     aStru[1]       A
       aStru[1,1]   C   CUST_NAME
       aStru[1,2]   C   SHIP_DATE
       aStru[1,3]   C   BALANCE
       aStru[1,4]   C   PRINT_FLAG
     aStru[2]       A
       aStru[2,1]   C   C
       aStru[2,2]   C   D
       aStru[2,3]   C   N
       aStru[2,4]   C   L
     aStru[3]       A
       aStru[3,1]   C   25
       aStru[3,2]   C   8
       aStru[3,3]   C   9
       aStru[3,4]   C   1
     aStru[4]       A
       aStru[4,1]   N   0
       aStru[4,2]   N   0
       aStru[4,3]   N   2
       aStru[4,4]   N   0

 Example of a "Ragged Symmetrical array":

                           Type  Contents

     aStru[1]       A
       aStru[1,1]   C   CUST_NAME
       aStru[1,2]   C   C
       aStru[1,3]   C   25
       aStru[1,4]   N   0
     aStru[2]       A
       aStru[2,1]   C   SHIP_DATE
       aStru[2,2]   C   D
       aStru[2,3]   C   8
       aStru[2,4]   N   0
     aStru[3]       A
       aStru[3,1]   C   BALANCE
       aStru[3,2]   C   N
       aStru[3,3]   C   9
       aStru[3,4]   N   2
     aStru[4]       A
       aStru[4,1]   C   PRINT_FLAG
       aStru[4,2]   C   L
       aStru[4,3]   C   1
       aStru[4, ]   N   0

Examples:

 PROCEDURE XTest()

 LOCAL aRaggedDir, aParallelDir, nChoice

 // Converting a Ragged array to a Parallel array

 aRaggedDir := Directory()
 aParallelDir := DC_ACONVERT( aRaggedDir )

 DC_Gui(.t.)

 nChoice := DC_Achoice( 10,10,20,40, aParallelDir[1] )

 DC_MsgBox( 'The size of ' + aParallelDir[1,nChoice] + ' is ' + ;
             Str( aParallelDir[2,nChoice] ) )

 RETURN

Files:

_DCARRAY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_areverse()


dc_addbuttonconfig()

Configure buttons added to dialogs by DCREAD GUI

DC_AddButtonConfig() is a Get-Set function which is used to configure the caption and size of buttons which are added to a dialog by the ADDBUTTONS or BUTTONS clause of DCREAD GUI.

Syntax:

DC_AddButtonConfig( <nButton> | <aConfig>, ;
                    [<xCaption>], ;
                    [<nWidth>], ;
                    [<nHeight>], ;
                    [<oBitmap>], ;
                    [<cFont>] ) -> aConfig

Returns:

An array of 4 elements containing the previous configuration of
the button.

Element  Type   Description
-------  ----- -----------------------------------------------
  [1]      N    Numeric value of button (DCGUI_BUTTON_*)
  [2]      X    Caption of button
  [3]      N    Width of button in pixels
  [4]      N    Height of button in pixels

Arguments:

<nButton> is the button to configure.  This is a manifest constant
from the DCGUI_BUTTON_* definitions in DCDIALOG.CH.

  DCGUI_BUTTON_OK - Configures the OK button
  DCGUI_BUTTON_CANCEL - Configures the CANCEL button
  DCGUI_BUTTON_EXIT - Configures the EXIT button
  DCGUI_BUTTON_HELP - Configures the HELP button
  DCGUI_BUTTON_YES - Configures the YES button
  DCGUI_BUTTON_NO - Configures the NO button

or <aConfig> is a 4 element array containing the numeric value
of the button to configure, the caption, the width and the height.

<xCaption> is the caption of the button.  This may be a character
string, a numeric resource value that has been linked into the
application, an XbpBitMap() object, or a string containing the
name of a .BMP, .JPG or .GIF file.  It may also be a code block
that returns one of the above values.

<nWidth> is the width of the button in pixels.

<nHeight> is the height of the button in pixels.

<oBitmap> is an XbpBitMap() object to use on the button.

<cFont> is the font compound name.

Examples:

#include "dcdialog.ch"
#include "dcbitmap.ch"

FUNCTION XTest()

LOCAL GetList[0], GetOptions, cUserID, cPassword, aOkConfig, aCancelConfig

cUserId := Space(10)
cPassword := Space(10)

aOkConfig := DC_AddButtonConfig(DCGUI_BUTTON_OK,BITMAP_OK_1,80,30)
aCancelConfig := DC_AddButtonConfig(DCGUI_BUTTON_CANCEL,BITMAP_CANCEL_1,80,30)

@ 1,1 DCSAY ' User ID' GET cUserID
@ 3,1 DCSAY 'Password' GET cPassword PASSWORD

DCGETOPTIONS ;
   BUTTONALIGN DCGUI_BUTTONALIGN_CENTER

DCREAD GUI FIT ADDBUTTONS TITLE 'Please Login' ;
   OPTIONS GetOptions

DC_AddButtonConfig(aOkConfig) // restore old configuration
DC_AddButtonConfig(aCancelConfig) // restore old configuration

RETURN nil

Files:

_DCGETBX.PRG, DCLIPX.DLL

See Also:

   DCREAD GUI
   DCGETOPTIONS


dc_addcargo()

Add cargo to the GetList

DC_ADDCARGO() is used to add cargo to the an array that is contained in the CARGO instance variable of the last GET in a GetList array.<br><br> DC_READMODAL() automatically looks at the information in CARGO to give added functionality to the GET system. CARGO is used to store array pointers, screen SAY information and other GET options.

Syntax:

DC_AddCargo ( <GetList>, ;
              <xCargo> ) -> GetList

Returns:

 A pointer to the <GetList> passed to DC_ADDCARGO().

Arguments:

<GetList> is the GetList array.

<xCargo> can be one of several numeric values or an array.

  xCargo        Description
  ------       ----------------------------------------
   101          Force this GET to validate
   102          Display Pick-list pointer icon (arrow)
  {103,bBlock}  Pre-Evaluate Code-Block
  {104,bBlock}  Post-Evaluate Code-Block
  {105,aMsg}    Message to display on screen
   106          Protect this GET from editing
   107          Capitalize first character of each word
  {108,aData}   SAY prompt and coordinates

Examples:

 #include "dcget.ch"

 LOCAL GetList := {}, aData, i

 use <cDataFile>
 aData := Array(Fcount())
 FOR i := 1 TO LEN( aData )
   aData[i] := FieldGet(i)
 NEXT
 DC_ReadWindow( { 10, 10, 20, 60 } )
 FOR i := 1 TO LEN(aData)

   DC_GetDevOut( i, 12, PadL(Field(i),10), )
   SetPos( Row(), Col()+1 )
   AAdd( GetList,_GET_(aData[i],"aData[i]",,,) )
   DC_GetDisplay( GetList )

   /* -- Add array element pointer -- */
   GetList := DC_ADDCARGO(GetList,-1*i)

   /* -- Add SAY Prompt and location -- */
   GetList := ;
      DC_ADDCARGO(GetList,{ 108, { i, 12, PadL(Field(i),10) }})

   /* -- Add CAPFIRST flag -- */
   GetList := DC_ADDCARGO(GetList,107)

 NEXT
 DC_ReadModal( GetList,,aReadArea )
 RETURN nil

Files:

_DCGETSY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()
   dc_readbox()


dc_addrec()

Append a new record and lock the record

The function of DC_ADDREC() is dependent on the APPEND MODE of operation that was previously selected by the DC_APPENDMODE() function.<br><br> If the Append Mode is 0 (default), then DC_ADDREC() will always append a Blank record.<br><br> If the Append Mode is 1, then DC_ADDREC() will first try to locate any existing Blank record in the database. If a Blank record is found, the record pointer will be set to the found record and the record will be locked. This mode functions differently based on whether or not the current work area has an index selected. If an index is selected, then it is assumed that blank records will always appear at the TOP of the database so only the first record is tested, otherwise the entire database will be search for a blank record.<br><br> If the Append Mode is 2, then DC_ADDREC() will first try to locate any existing record that is marked for deletion. If a deleted record is found, the record pointer will be set to the found record, the record will be recalled (undeleted), all fields will be blanked, and the record will be locked.<br><br>

Syntax:

 DC_AddRec ( [<nWaitTime>], ;
             [<lDisplayError>], ;
             [<nAppendMode>] ) -> lStatus

Returns:

 A logical .TRUE. if the record is successfully locked.

Arguments:

<nWaitTime> is the number of seconds to wait for the system to
return a lock before returning the status or the error message.
(0 = wait forever).

<lDisplayError> if .true. will display an operator error
message if the record cannot be locked. (default) or if .false.
will not display an error message to the operator.

<nAppendMode> is a number from 0 to 2 (0 is the default) to
establish the mode for reusing deleted or blank records, if
they exist, or appending a new record.  See DC_APPENDMODE().

Examples:

 dc_appendmode(1)  // reuse blank records
 use sales
 if DC_ADDREC()
   replace date with date()
 else
   break
 endif

Files:

_DCLOCK.PRG, DCLIPX.DLL

See Also:

   dc_reclock()
   dc_filock()
   dc_appendmode()
   APPEND
   UNLOCK


dc_addsetkeys()

Convert all SET KEYS to DCHOTKEY commands

DC_ADDSETKEYS is used to read the current SET KEYS and add them to the GetList as DCHOTKEY commands.<br><br>

Syntax:

 DC_AddSetKeys( <aGetList> ) -> aGetList

Returns:

 A GetList array with all hotkeys added.

Arguments:

<aGetList> is the GetList array that will be passed to DC_ReadGUI().

Examples:

FUNCTION XTest()

LOCAL GetList := {}, dDate := Date(), nNumber := 0

SET KEY -2 TO DC_PopDate()
SET KEY -3 TO DC_PopCalc()

@ 1,1 DCSAY '  Enter a Date' GET dDate
@ 3,1 DCSAY 'Enter a Number' Get nNumber

@ 5,1 DCSAY 'Press F3 for a Calendar' SAYSIZE 30
@ 6,1 DCSAY 'Press F4 for a Calculator' SAYSIZE 30

DC_ADDSETKEYS(GetList)

DCREAD GUI FIT ADDBUTTONS

RETURN nil

Files:

_DCFUNCT.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readgui()
   DCHOTKEY


DC_AdsCursor2Excel()

Create Excel spread sheet from an Ads Cursor handle

DC_AdsCursor2Excel() is used to create an Excel spread sheet from an Ads Cursor handle.

Syntax:

DC_AdsCursor2Excel( <nCursorHandle>, ;
                    [<cExcelFile>], ;
                    [<nOrientation>], ;
                    [<lDisplayAlerts>], ;
                    [<lVisible>], ;
                    [<lAutoFit>] ) -> nil

Arguments:

<cExcelFile> is the name of the excel file (*.XLS) to be created.
If this parameter is not passed, the file will be created in the
same directory as the application .exe and will be named WORKSHEET.XLS.

<nOrientation> is the orientation of the spreadsheet.  A value of
1 creates a "portrait" orientation.  A value of 2 creates a
"landscape" orientation (default).

<lDisplayAlerts> will prompt the user if the file being created
will be overwritten.  The default is .f.

<lVisible> will display the spreadsheet while the cells are being
filled.  Default is .f.

<lAutoFit> will optimize the columns of the spreadsheet to fit
the data to it's optimum width, otherwise the columns will be
the width of the database field.  Default is .t.

Examples:

FUNCTION Xtest()

LOCAL nHandle, cServer := CurDrive()+':', nStatementHandle, ;
      cStatement

cStatement := "SELECT PART_NO, ON_HAND, COST FROM PARTS WHERE ON_HAND > 100"

AdsConnect( cServer, @nHandle )

nStatementHandle := 0
AdsCreateSQLStatement( nHandle, @nStatementHandle )

nCursorHandle := 0
AdsExecuteSQLDirect( nStatementHandle, cSelect, @nCursorHandle )

DC_AdsCursor2Excel( nCursorHandle )

RETURN nil

Files:

_DCADS.PRG

See Also:

   DC_WorkArea2Excel()
   DC_Array2Excel()


dc_adscursor2xml()

Export an ADS cursor to an XML file or string

DC_AdsCursor2Xml() will export an ADS cursor to an XML file, or string, that will contain structure and data. Look at the example in .\samples\xml.

Files:

_dcfunct.prg, dclipx.dll

See Also:

   dc_adscursor2excel()


dc_adsfieldblock()

Create a Get/Set code block for an ADS SQL cursor field

DC_AdsFieldBlock() is used to create a Get/Set code block for a field in an ADS SQL cursor.

Syntax:

DC_AdsFieldBlock( <nCursor> , ;
                  <cFieldName>, ;
                  [<bFormat>] ) -> bGetSet

Returns:

A code block.

Arguments:

<nCursor> is a numeric cursor returned by an ADS SQL statement.

<cFieldName> is a name of a field in the ADS SQL cursor.

<bFormat> is a code block to format the returned data. The code
block receives the data in for form of a string.

Examples:

nCursorHandle := 0
AdsExecuteSQLDirect( nStatementHandle, cSelect, @nCursorHandle )

nNumFields := 0
AdsGetNumFields( nCursorHandle, @nNumFields )

bDataSource := {||nCursorHandle}
@ 0,0 DCBROWSE oBrowse ;
      DATA bDataSource ;
      SIZE 100,20 ;
      PRESENTATION DC_BrowPres()

FOR i := 1 TO nNumFields

  cFieldName := Space(20)
  nLength := 20
  AdsGetFieldName( nCursorHandle, i, @cFieldName, @nLength )
  cFieldName := Pad(cFieldName,nLength)

  bGetSet := Adsfieldblock( nCursorHandle, cFieldname )
  DCBROWSECOL DATA bGetSet PARENT oBrowse HEADER cFieldName ;
     WIDTH 20

NEXT

Files:

_DCADS.PRG, DCLIPX.DLL

See Also:

   DC_AdsSQLQuery()


dc_adsgoposition()

Moves the row pointer to a percent position in a ADS SQL cursor

DC_AdsGoPosition() moves the row pointer in an ADS SQL cursor based on a percent value.

Syntax:

DC_AdsSkipper( <nAdsSQLcursor>, ;
               <nPercent> ) -> Nil

Returns:

A numeric value equal to the actual number of rows skipped.

Arguments:

<nAdsSQLcursor> is an ADS SQL cursor.

<nPercent> is a numeric value in the range between 0 and 100.
Zero is equivalent to the first row and 100 indicates the last
row in a SQL cursor.

Examples:

oBrowse:GoPosBlock := {|n|DC_AdsGoPosition(nAdsSQLcursor,n)}

Files:

_DCADS.PRG, DCLIPX.DLL

See Also:

   dc_adsfieldblock()
   dc_adsskipper()


dc_adsposition()

Returns the position of the ADS SQL cursor row as a percent value

DC_AdsPosition() returns a numeric value in the range between 0 and 100. It indicates the position of the row pointer of an ADS SQL cursor in percent.

Syntax:

DC_AdsSkipper( <nAdsSQLcursor> ) -> nPercent

Returns:

A numeric value equal to the position of the row in percent.

Arguments:

<nAdsSQLcursor> is an ADS SQL cursor.

Examples:

oBrowse:PosBlock := {|n|DC_AdsPosition(nAdsSQLcursor)}

Files:

_DCADS.PRG, DCLIPX.DLL

See Also:

   dc_adsfieldblock()
   dc_adsskipper()


dc_adsrunsql()

Execute a SQL statement in a new work area

DC_AdsRunSql() will execute a SQL SELECT statement and return the results in a work area which can be navigated with standard Xbase++ navigation functions such as dbSkip(), dbGoTop(), etc.<br><br>This requires Xbase++ 1.9 or later and ADSDBE 1.9 or later.<br><br>Before using this function, a connection must be made to ADS server and a data-dictionary file. See DC_AdsSession().<br><br>

Syntax:

DC_AdsRunSQL( <cSQLStatement>, ;
              [<cAlias>] ) -> lStatus

Returns:

A logical .TRUE. if the statement executed successfully, .FALSE.
otherwise.

Arguments:

<cSQLstatement> is an SQL SELECT statement that references tables
in an ADS data-dictionary.

Examples:

cServer := DC_Path(AppName(.t.)) + 'sample.add'

oSession := DC_AdsSession( cServer )

TEXT INTO cStatement
SELECT * FROM XTEST
ENDTEXT

DC_AdsRunSql( cStatement, 'XTEST' )

Browse()

Files:

_DCADS.PRG, DCLIPX.DLL

See Also:

   dc_adsstatement()
   dc_adssession()


dc_adssession()

Create or return Ads DacSession for current thread

DC_AdsSession is used to create an ADSDBE DacSession for the current thread to be later used by DC_AdsStatement() or a regular dbUseArea().<br><br>All sessions for all threads are stored in a static multi-dimensional array.<br><br>

Syntax:

DC_AdsSession( [<ocSession>], ;
               [<nWhich>], ;
               [<lReturnAll>] ) -> oDacSession

Returns:

A DacSession() object.

Arguments:

<ocSession> may be a connect string or a DacSession() object.

If it is a character string then it must be a valid connection
string to send to ADS.  It may be the drive/path where the databases
reside or the drive path of an ADS data-dictionary file.  A connect
string will cause a new ADS connect to be created.

If it is a DacSession() object, then no new connection will be
created and the passed object will be stored in the connection
array.

<nWhich> is the number of the session to store for the current
thread.  The default is 1.  For example, each thread could have
2 Ads Session objects stored, 1 for Free Table connections, and
another for Data-Dictionary connections.

<lReturnAll> if .TRUE. will return the entire multi-dimensional
array.

Notes:

The ADSDBE must be loaded before calling this function.

Examples:

FUNCTION Xtest()

LoadDbes()

cServer := DC_Path(AppName(.t.)) + 'sample.add'

oSession := DC_AdsSession( cServer )

TEXT INTO cStatement
SELECT * FROM XTEST
ENDTEXT

oStatement := DC_AdsStatement():new(cStatement)
cAlias := oStatement:execute()
Browse()

oStatement:close()
oSession:disConnect()

RETURN nil

* -----------------

FUNCTION LoadDbes()

LOCAL cSession, aDbeList := dbeList()

IF ! DbeLoad( "ADSDBE" )
  DC_WinAlert( "Unable to load ADSDBE", "ADS Server",, ;
        XBPMB_WARNING + XBPMB_APPMODAL )
ELSE

  DbeSetDefault( "ADSDBE" )

  DbeInfo( COMPONENT_DATA, ADSDBE_TBL_MODE, ADSDBE_CDX )
  DbeInfo( COMPONENT_ORDER, ADSDBE_TBL_MODE, ADSDBE_CDX )
  DbeInfo( COMPONENT_DATA, ADSDBE_LOCK_MODE, ADSDBE_PROPRIETARY_LOCKING  )

  cSession := "DBE=ADSDBE;SERVER=" + scDictServer
  soAdsSessionDict := DacSession():new(cSession)
  IF !soAdsSessionDict:isConnected()
    MsgBox( "Unable to establish DICTIONARY connection to ADS Server" + Chr(13) + ;
             cSession + Chr(13) + ;
             "Error Code: " + Alltrim(Str(soAdsSessionDict:getLastError())) + Chr(13) + ;
              soAdsSessionDict:getLastMessage() )
  ELSE
    DC_AdsSession( soAdsSessionDict,1 )
  ENDIF

  cSession := "DBE=ADSDBE;SERVER=" + scFreeServer
  soAdsSessionFree := DacSession():new(cSession)
  IF !soAdsSessionFree:isConnected()
    MsgBox( "Unable to establish FREE connection to ADS Server" + Chr(13) + ;
            cSession + Chr(13) + ;
            "Error Code: " + Alltrim(Str(soAdsSessionFree:getLastError())) + Chr(13) + ;
             soAdsSessionFree:getLastMessage() )
  ELSE
    DC_AdsSession( soAdsSessionFree, 2 )
  ENDIF

ENDIF

RETURN nil

Files:

_DCADS.PRG, DCLIPX.DLL

See Also:

   dc_adsstatement()


dc_adsskipper()

A skipper for ADS SQL cursors

DC_AdsSkipper() is a Skipper function to be used in navigation code blocks for a browse.

Syntax:

DC_AdsSkipper( <nAdsSQLcursor>, ;
               <nWantSkip> ) -> nDidSkip

Returns:

A numeric value equal to the actual number of rows skipped.

Arguments:

<nAdsSQLcursor> is an ADS SQL cursor.

<nWantSkip> is the number of rows to skip.

Examples:

oBrowse:skipBlock := {|n|DC_AdsSkipper(nAdsSQLcursor,n)}

Files:

_DCADS.PRG, DCLIPX.DLL

See Also:

   dc_adsfieldblock()


dc_adssqlquery()

A SQL Query window for ADS

DC_AdsSQLQuery() is a SQL query system based on the SQL functions in ACE32.DLL.<br><br>SQL statements are entered in a text window and then executed with the push of a button. A SQL cursor is returned and the results are displayed in a columnar browse window. <br><br>SQL statements may be saved to a database named ADSSQL.DBF for later retrieval.<br><br>

Syntax:

DC_AdsSQLQuery( [<cServer>], ;
                [<cUserName>], ;
                [<cPassword>], ;
                [<cDataPath>], ;
                [@<cBrowseObjectName>], ;
                [<oParent>], ;
                [<nIndexMode>, ;
                [<nLockingMode>, ;
                [<cDbe>] ) -> nil

Returns:

Nil.

Arguments:

<cServer> is either a path to a set of .DBF / .CDX databases or
the name of an ADS data-dictionary file.  If this parameter is
not passed then it will default to <cDataPath>.

<cUserName> and <cPassword> are used only if <cServer> is a
data-dictionary file.  This is a valid user and password to allow
access to the data-dictionary.

<cDataPath> is the directory where the ADSSQL.DBF file is to
be opened or created.  ADSSQL.DBF is used to save SQL queries.

<oParent> is a pointer to a parent object for the new dialog.
If <oParent> is empty, then the parent will be the AppDeskTop().

<nIndexMode> is the type of index files to be used with the DBF
databases.  The default is ADS_CDX (defined in DCADS.CH).

<nLockingMode> is the type of record locking scheme to use.
The default is ADS_COMPATIBLE_LOCKING (defined in DCADS.CH).

<cDbe> is the DBE to use for the ADSSQL.DBF database.  The default
is 'DBFNTX'.

Files:

_DCADS.PRG, DCLIPX.DLL

See Also:


dc_alert()

A Dual-Mode replacement for Clipper's ALERT() function

DC_ALERT() is a Dual-mode replacement for Alert(). When the GUI flag is ON, DC_ALERT() functions similiar to Alert() except that it is displayed in GUI mode. When the GUI flag is OFF, DC_ALERT() functions identical to Alert() except it is also activated by a mouse. The left button of the mouse is used to select the item in the window.

Syntax:

DC_Alert ( <cText>, ;
           <aMenuItems>, ;
           [<cColorString>], ;
           [<lJustify>], ;
           [<aMenuId>], ;
           [<cMenuName>], ;
           [<nChoice>], ;
           [@<aDlgPos>], ;
           [<aFonts>] ) -> nChoice

Returns:

 A number equal to the menu choice.  Returns 0 if user
 presses ESCape.

Arguments:

<cText> is the message to place in the alert box.  Use
semicolons in the text to separate lines of text.

<aMenuItems> is an array of menu choices.  The character
following the '~' character will be highlighted.

<cColorString> is an optional color string containing
exactly 4 colors separated by commas:

 (1) box and message.
 (2) unselected menu items.
 (3) hot-key character of each unselected menu item
 (4) selected menu item

<lJustify> if .TRUE. will left-justify the message items.
Default is .FALSE.

<aMenuId> - An optional array of unique Menu ID codes (up to 8
characters) for each menu item in <aItems>.  This array is
needed to enable the PERSISTENT MENU SELECTION feature.  See
DC_MenuPull() for more information.

<cMenuName> - An optional parameter with a "unique" name for
this menu.  This name is needed to enable the PERSISTENT MENU
SELECTION feature.  See DC_MenuPull() for more information.

<nChoice> is the default menu selection.

@<aDlgPos> is a numeric variable to store a two-element array
of coordinates which will be returned when the user exists the
alert window.  These coordinates are the screen coordinates of
the dialog before it was destroyed.  These coordinates may be
passed to DG_GUIALERT() again later to paint the dialog window
in the same location.

<aFonts> is a 2-element array containing the Font Compound Name
for the buttons and the text.  Element 1 is the button font and
element 2 is the text font.  This parameter is used in GUI mode
only.

Notes:

The foreground and background color of the GUI alert box ispreset by the function DC_AlertColor().

Examples:

 PROCEDURE XTest()

 LOCAL nChoice

 DC_Gui(.t.)

 nChoice := DC_ALERT( "The printer is not ready",;
           { 'Retry','Abort','Output to a file' } )

 DC_MsgBox( 'You chose ' + Str(nChoice) )

 RETURN

Files:

_DCMENU2.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_msgbox()
   dc_guialert()


dc_andbits()

A logical AND of two bytes

DC_ANDBITS() will produce the result of logically ANDing two bytes.<br><br>

Syntax:

DC_AndBits( <nNum1>, ;
            <nNum2> ) ->nResult

Returns:

 A numeric value from 0 - 255

Arguments:

<nNum1> and <nNum2> are numeric values from 0 to 255.

Files:

_DCAND.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_bittest()
   dc_xorbits()


dc_apick()

A dialogue for choosing a item from an array pick list.

DC_APick() is used to display a browse-style picklist of an array.<br><br>

Syntax:

DC_APick ( [<nTop>], [<nLeft>], <nWidth>, <nHeight>, ;
           <aMenuItems>, ;

           [<acHeader>], ;
           [<anWidth>], ;
           [<cTitle>], ;
           [<anTag>], ;
           [<aTagColor>], ;

           [<bHandler>], ;
           [<nStart>], ;
           [<cFontName>], ;
           [<oParent>], ;
           [<oOwner>], ;
           [<lCenter>], ;
           [<lMenu>], ;
           [<lNoVScroll>], ;
           [<lNoHScroll>], ;
           [<aPres>], ;
           [<cHelpCode>], ;
           [<cAutoSeekPicture>], ;
           [<lNoRestore>] ) -> nChoice

Returns:

A Numeric Value equivalent to the selected row.

Arguments:

<nTop>, <nLeft> are the starting coordinates.  These are text-
base coordinates.  These parameters are not required if the
<lCenter> parameter is used.

<nWidth> and <nHeight> are the width and height of the window
in text-based coordinates.

<aMenuItems> is an array of character strings to include
in the pick-list.  This may be a single-dimension array or a
multi-dimension array.

<acHeader> is the heading to place above each column.  If
<aMenuItems> is a single-dimension array, then there is only 1
header, so <acHeader> is a character string.  If <aMenuItems>
is a multi-dimension array, then <acHeader> is an array of
character strings, 1 for each column.

<anWidth> is the width of the column(s).  If aMenuItems> is a
single-dimension array, then there is only 1 width, so <anWidth>
is a numeric value.  If <aMenuItems> is a multi-dimension array,
then <anWidth> is an array of numeric values, 1 for each column.

<cTitle> is the title to place at the top of the window.

<anTag> is an array of logical elements or a single numeric
value.  If <anTag> is an array, it must be the same length as
the array being browsed and must contain logical values.  When
the user double-clicks a browse row, the corresponding element
of <anTag> will be toggled.  If <anTag> is a numeric value, then
it is a pointer to the column of <aMenuItems> that contains
logical tags.

<aTagColor> is used in conjunction with <anTag> to select the
color for the rows that are tagged.  This is a 2-element array
consisting of a foreground and background color.  The default
is { GRA_CLR_WHITE, GRA_CLR_BLUE }.

<bHandler> is a SPARE.

<nStart> is the starting element in the browse.

<cFontName> is the font to use for the browse.

<oParent> is the parent object to create the browse.  If no
parameter is passed, a dialog window will be created.

<oOwner> is the owner object of the browse.  If no parameter is
passed, the owner will be the same as the parent.

<lCenter> if .TRUE. will center the browse dialog on the desktop.

<lMenu> if .TRUE. will enable "menu mode".  This allows the
operator to press keyboard keys that match the first letter of
each array item to select the item.

<lNoVScroll> if .TRUE. will suppress the vertical scroll bar.
The default is .FALSE.

<lNoHScroll> if .TRUE. will suppress the horizontal scroll bar.
The default is .FALSE.

<aPres> is an array of presentation parameters that must conform
to the presParam specifications for the XbpBrowse() class.

<cHelpCode> is a help code.

<cAutoSeekPicture> if passed will cause an autoseek GET to be
created above the browse window.  The value entered into the
get will be passed to DC_BrowseAutoSeek() to seek to a value.
<cAutoSeekPicture> establishes the picture clause for the Get.

<lNoRestore> if .TRUE.  will override DC_AutoRestoreWindow() and
insure that the window coordinates and size are never saved and
restored.  The default is .FALSE.

Examples:

FUNCTION XTest()

LOCAL aDir := Directory(), i, aHeaders, aWidths

FOR i := 1 TO Len(aDir)
  ASize(aDir[i],5)

  aDir[i,5] := .f.
NEXT

aHeaders := { 'File Name', 'File Size', 'File Date', 'File Time' }

aWidths := { 10,10,10,10 }

nChoice := DC_APick ( , , 50, 10, aDir, ;
           aHeaders, aWidths, 'Disk Directory', 5, ;
           { GRA_CLR_WHITE, GRA_CLR_RED }, ;
           nil, nil, '8.Terminal', nil, nil, .t. )

RETURN nChoice

Files:

_DCACHOI.PRG/.OBJ, DCLIPX.LIB

See Also:

   DCAPICK
   dc_achoice()


dc_appendmode()

Set the default mode of operation for DC_AddRec()

DC_APPENDMODE() is used to establish the default operation of the DC_ADDREC() function. Depending on the mode selected DC_ADDREC() will attempt to reuse blank records or deleted before appending a new, blank record.<br><br>

Syntax:

 DC_AppendMode ( <nMode> ) -> nOldMode

Returns:

 A numeric value representing the current append mode.

Arguments:

<nMode> is a number designating the desired append mode.

If the Append Mode is 0 (default), then DC_ADDREC() will always
append a Blank record.

If the Append Mode is 1, then DC_ADDREC() will first try to
locate any existing Blank record in the database.  If a Blank
record is found, the record pointer will be set to the found
record and the record will be locked.  This mode functions
differently based on whether or not the current work area
has an index selected.  If an index is selected, then it is
assumed that blank records will always appear at the TOP of
the database so only the first record is tested, otherwise
the entire database will be search for a blank record.

If the Append Mode is 2, then DC_ADDREC() will first try to
locate any existing record that is marked for deletion.  If
a deleted record is found, the record pointer will be set
to the found record, the record will be recalled (undeleted),
all fields will be blanked, and the record will be locked.

Examples:

 use sales
 set index to month
 DC_APPENDMODE(1)  // re-use blank records
 if dc_addrec()
   replace date with date()
 else
   break
 endif

Files:

_DCLOCK.PRG, DCLIP1.DLL

See Also:

   dc_addrec()


dc_appevent()

Post an Event Loop

DC_APPEVENT() is a handy function that creates an event loop for processing events. Unlike the Xbase++ AppEvent() function, DC_APPEVENT() contains a DO..WHILE loop that processes events as a single function call.

Syntax:

 DC_AppEvent( @<lOk>, ;
               <nExitEvent>, ;
               <nDelay> ) -> nLastEvent

Returns:

 A numeric value equal to the last event processed in the loop.

Arguments:

@<lOk> is an optional logical value (passed by reference).
DC_AppEvent() will exit and return when this value is set to
.FALSE.

<nExitEvent> is an optional numeric value.  DC_AppEvent() will
exit and return when the next event in the event queue is
equal to this value.  <nExitEvent> defaults to 0, meaning that
the loop will exit when no more events are in the event queue.

<nDelay> is the amount of delay to use when DC_AppEvent() calls
the AppEvent() function.  This defaults to 0, meaning that
event loop will not exit until an event occurs.  If <nDelay>
is any value greater than 0, then this is amount of delay before
the AppEvent() function exits.  <nDelay> should usually be set
to a value of .01 when using DC_AppEvent() to process events
while still processing other code.  See the example.

Examples:

/*
This example uses DC_APPEVENT() to abort a COPY TO process.
*/

#include 'dcdialog.ch'

FUNCTION XTest()

LOCAL Getlist := {}, oProgress, oDialog, lOk := .t., oButton, ;
      nEvent, mp1, mp2, oXbp

USE COLLECT VIA DBFNTX NEW SHARED

@ 2,5 DCSAY 'Exporting Data to JUNK.DBF'

@ 4,5 DCPROGRESS oProgress ;
       SIZE 55,1.5 ;
       MAXCOUNT RecCount() COLOR GRA_CLR_BLUE

@ 4,65 DCPUSHBUTTON  CAPTION '&Cancel' ;
  ACTION {||lOk:=.f.} OBJECT oButton ;
  SIZE 8,1.5

DCREAD GUI TITLE 'My Test Dialog' ;
   PARENT @oDialog ;
   FIT ;
   EXIT

oDialog:show()

COPY TO junk WHILE _Progress( oProgress, @lOk )

oButton:SetCaption('&Ok')
DC_APPEVENT( @lOk )

oDialog:Destroy()
CLOSE ALL

RETURN nil

/* ----------------- */

STATIC FUNCTION _Progress ( oProgress, lOk )

DC_GetProgress( oProgress, COLLECT->(RecNo()) )
DC_Pause(.3)
DC_APPEVENT( @lOk, 0, .01 )

RETURN lOk

Files:

_DCGETBX.PRG/.OBJ, DCLIPX.LIB


dc_appeventdefine()

Translate AppEvent() value to DEFINE value

DC_APPEVENTDEFINE() returns a character string that contains the DEFINITION name for the AppEvent() value. These defines are contained in APPEVENT.CH. This is a handy debugging function that can be used in event loops to display events as they are occurring like so:<br><br> DO WHILE nEvent # xbeP_None nEvent := AppEvent( @mp1, @mp2, @oXbp ) ? DC_APPEVENTDEFINE( nEvent ) oXbp:HandleEvent( nEvent, mp1, mp2 ) ENDDO

Syntax:

DC_AppEventDefine( <nEvent> ) -> cDefinition

Returns:

 A Character string.

Arguments:

<nEvent> is the AppEvent() to translate.

Examples:

 #include 'appevent.ch'

 PROCEDURE XTest()

 DC_Gui(.t.)

 DC_MsgBox( { DC_APPEVENTDEFINE( xbeP_Close ), ;
              DC_APPEVENTDEFINE( xbeP_Resize ), ;
              DC_APPEVENTDEFINE( xbeP_Activate ) } )

 RETURN

Files:

_DCPUTK.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_keytran()
   dc_appkeydefine()


dc_appkeydefine()

Translate AppEvent() keyboard value to DEFINE value

DC_APPKEYDEFINE() returns a character string that contains the DEFINITION name for the AppEvent() a keyboard value. These defines are contained in APPEVENT.CH. This is a handy debugging function that can be used in event loops to display events as they are occurring like so:<br><br> DO WHILE nEvent # xbeP_None nEvent := AppEvent( @mp1, @mp2, @oXbp ) IF nEvent = xbeP_Keyboard ? DC_APPKEYDEFINE( mp1 ) ENDIF oXbp:HandleEvent( nEvent, mp1, mp2 ) ENDDO

Syntax:

DC_AppKeyDefine( <nKey> ) -> cDefinition

Returns:

 A Character string.

Arguments:

<nKey> is the AppEvent() value of the key to translate.

Examples:

 #include 'appevent.ch'

 PROCEDURE XTest()

 DC_Gui(.t.)

 DC_MsgBox( { DC_APPKEYDEFINE( xbeK_ALT_M ), ;
              DC_APPKEYDEFINE( xbeK_ENTER ), ;
              DC_APPKEYDEFINE( xbeK_INS ) } )

 RETURN

Files:

_DCPUTK.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_keytran()
   dc_appeventdefine()


dc_applysqlparams()

Apply SQL parameters to a SQL statement.

DC_ApplySQLParams() is use to pass parameters into a SQL statement. The parameters may be type C, L, M, N, or D. Each ? in the statement will be replaced by each passed parameter, sequentially, Each parameter is converted to a character string value which is compatible with SQL.

Syntax:

DC_ApplySQLparams( <cSQLstatement>, ;
                   <aParams> ) -> <cSQLstatement>

Returns:

A character string.

Arguments:

<cSQLstatement> is a SQL statement that contains one ? character
for each parameter in <aParams>.

<aParams> is an array of values to plug into the SQL statement.

If a parameter is enclosed in brackets, then the value in the
brackets is considered "literal" and is stuffed into the SQL command
as is without the brackets.

Examples:

cSQL := 'SELECT * FROM customers WHERE name=? AND zip=?'

cSQL := DC_ApplySQLParams( cSQL, {'Donnay', '83706'})

Files:

_DCADS.PRG, DCLIPX.DLL

See Also:

   dc_adsstatement()
   dc_var2sql()


dc_ar2str()

Convert a multidimensional array to a string

DC_Ar2Str() will convert the contents of any multi-dimensional array to a string for later restoring with DC_Str2Ar(). The string may then be saved to a file or to a character or memo type database field. This set of functions is an alternative to using the Xbase++ functions Var2Bin() and Bin2Var() because they will create a runtime error if the array contains code blocks with non-persistent data.<br><br> If the array contains code blocks, the code blocks will be saved and restored provide that they contain persistent data. Any code block that contains non-persistent data will be saved as a NIL.<br><br> If the array contains pointers to objects, they pointers will be saved as a NIL.<br><br>

Syntax:

DC_Ar2Str ( <aArray> ) -> cString

Returns:

 A character string.

Arguments:

<aArray> is any multidimenstional array.

Examples:

 PROCEDURE XTest()

 LOCAL aDir

 aDir := Directory()

 USE dirs
 APPEND BLANK
 REPL DIRS->array WITH DC_Ar2Str(aDir)

 aDir := DC_Str2Ar(DIRS->array)
 DC_ArrayView(aDir)

 RETURN

Files:

_DCASAVE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_str2ar()
   dc_asave()


dc_arestore()

Restore a multidimensional array from a binary file

DC_ARESTORE() will create an multidimensional array from the contents of a binary file that was created with DC_ASAVE().<br><br> If the array contains code blocks, the code blocks will be saved and restored provide that they contain persistent data. Any code block that contains non-persistent data will be restored as a NIL.<br><br> If the array contains pointers to objects, they pointers will be restored as a NIL.

Syntax:

DC_ARestore ( <cFileName> ) -> aArray

Returns:

 A multidimensional array if the array file was a valid file,
 otherwise returns a NIL.

Arguments:

<cFileName> is the name of the binary file that was previously
created with DC_ASAVE().

Examples:

 PROCEDURE XTest()

 LOCAL aDir1, aDir2

 DC_Gui(.t.)

 aDir1 := Directory()
 dc_asave( aDir1, 'ADIR.ARX' )
 aDir2 := DC_ARESTORE( 'ADIR.ARX' )

 DC_Achoice( 5,10,20,30, DC_AConvert( aDir2 )[1] )

 RETURN

Files:

_DCASAVE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_asave()


dc_areverse()

Reverse all elements in an array

DC_AREVERSE() is used to sort all the elements of an array in reverse order from the original array.<br><br>

Syntax:

 DC_AReverse ( <aArray> ) -> aNewArray

Returns:

 An array of the same length as the original array.

Arguments:

<aArray> is the name of the array to reverse.

Examples:

 myArray :=  { 1, 2, 'test', .t. }

 outArray := DC_AREVERSE( myArray )

 // contents of outArray :  { .t., 'test', 2, 1 }

Files:

_DCARRAY.PRG, DCLIP1.DLL

See Also:

   dc_aconvert()


dc_array_r()

Create a multi-dimensional array from an array text file

DC_ARRAY_R() is used to create a multi-dimensional array from the contents of an array text file. Only elements of the type L (logical), N (numeric), C (character), D (date), A (array) can be saved and restored.

Syntax:

DC_Array_Read ( <cArrayFile> ) -> aArray

Returns:

 A multi-dimensional array built from the contents of <cArrayFile>.

Arguments:

<cArrayFile> is the name of the array text file to read.

Examples:

 PROCEDURE XTest()

 LOCAL aDir1, aDir2, cScrn

 DC_Gui(.t.)

 cScrn := DC_WaitOn()
 aDir1 := directory()
 dc_array_w( aDir1, "DIR.AR" )
 aDir2 := DC_ARRAY_R( "DIR.AR" )
 DC_Impl(cScrn)

 DC_Achoice( 5,10,20,30, DC_AConvert( aDir2 )[1] )

 RETURN

Files:

_DCARRAY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_array_w()


dc_array_w()

Write contents of a multi-dimensional array to file

DC_ARRAY_W() is used to save a multi-dimensional array to an array text file for later restoring with the DC_ARRAY_R() function for RESTORE ARRAY command. Only elements of the type L (logical), N (numeric), C (character), D (date), A (array) can be saved and restored.

Syntax:

DC_Array_Write ( <aArray>, ;
                 <cArrayFile> ) -> lStatus

Returns:

 .TRUE. if the array file was created, .FALSE. otherwise.

Arguments:

<aArray> is the name of the multi-dimensional array to save.

<cArrayFile> is the name of the array text file to write.

Examples:

 PROCEDURE XTest()

 LOCAL aDir1, aDir2, cScrn

 DC_Gui(.t.)

 cScrn := DC_WaitOn()
 aDir1 := directory()
 DC_ARRAY_W( aDir1, "DIR.AR" )
 aDir2 := dc_array_r( "DIR.AR" )
 DC_Impl(cScrn)

 DC_Achoice( 5,10,20,30, DC_AConvert( aDir2 )[1] )

 RETURN

Files:

_DCARRAY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_array_r()


dc_array2csv()

Create a comma-delimeted CSV file from data in an array

DC_Array2CSV() is use to create a comma-delimited (*.CSV) file from the data in a 2-dimensional array.

Syntax:

DC_Array2CSV( <cCsvFile>, ;
              <aData>, ;
              [<aHeader>] ) -> lStatus

Returns:

A logical .true. if the file could be created, .false. otherwise.

Arguments:

<cCsvFile> is the name of the comma-delimted file (*.CSV) to be created.

<aData> is a 2-dimensional array containing the data.

<aHeader> is a 1-dimensional array with header information.

Examples:

aDir := Directory()

aHeader := { 'File Name', 'File Size', 'File Date' ,'File Time' }

DC_Array2CSV('DIRECTORY.CSV',aHeader)

DC_SpawnUrl('DIRECTORY.CSV')

Files:

_DCFUNCT.PRG, DCLIPX.DLL, DCLIPX.LIB


dc_array2excel()

Create an Excel Spreadsheet from data in an array

DC_Array2Excel() is use to create an Excel spreadsheet (*.XLS) file from the data in a 2-dimensional array.

Syntax:

DC_Array2Excel( [<cExcelFile>], ;
                <aData>, ;
                [<nOrientation>], ;
                [<lDisplayAlerts>], ;
                [<lVisible>], ;
                [<lAutoFit>], ;
                [<lTrimNilColumns>], ;
                [<lCombineSheets>], ;
                [<cPassWord>], ;
                [<lFreezeRow1>], ;
                [<lCSVFallBack>] ) -> lStatus

Returns:

A logical .true. if the spreadsheet could be created, .false.
otherwise.

Arguments:

<cExcelFile> is the name of the excel file (*.XLS) to be created.
If this parameter is not passed, the file will be created in the
same directory as the application .exe and will be named WORKSHEET.XLS.

<aData> is the array containing the data.  This must be an array
of 2-dimensional sub-arrays (one for each Excel sheet).

<nOrientation> is the orientation of the spreadsheet.  A value of
1 creates a "portrait" orientation.  A value of 2 creates a
"landscape" orientation (default).

<lDisplayAlerts> will prompt the user if the file being created
will be overwritten.  The default is .f.

<lVisible> will display the spreadsheet while the cells are being
filled.  Default is .f.

<lAutoFit> will optimize the columns of the spreadsheet to fit
the data to it's optimum width, otherwise the columns will be
the width of the database field.  Default is .t.

<lTrimArray> will remove all columns and rows from the array that
contain all NIL values to optimize the resultant spreadsheet. The
default is .f.

<lCombineSheets> will create a single Excel sheet from the data
in all subarrays.  Instead of writing the data to separate sheets
the data from each sheet will be added as additional rows to
the first sheet.  The default is .f.

<cPassWord> is an optional password to assign to the file.

<lFreezeRow1> if .TRUE. causes the first row of the Excel sheet to be
bold font and locked from scrolling.  The default is .FALSE.

<lCsvFallBack> if .TRUE. will cause the output to be a .CSV file in
the event that the Excel ActiveX control is not installed.

Examples:

aDir := Directory()

aDir := { aDir }

DC_Array2Excel('DIRECTORY.XLS',aDir)

DC_SpawnUrl('DIRECTORY.XLS')

Files:

_DCFUNCT.PRG, DCLIPX.DLL, DCLIPX.LIB


dc_array2hexstring()

Convert a multidimensional array to a hex string

DC_Array2HexString() will convert the contents of any multi-dimensional array to a string for later restoring with DC_HexString2Array(). The string may then be saved to a file or to a character or memo type database field. <br><br>This function is mainly intended for use on the internet when an array of information must be passed in an XML stream.<br><br><br><br>

Syntax:

DC_Array2HexString ( <aArray> ) -> cString

Returns:

 A character string.

Arguments:

<aArray> is any multidimensional array that contains variables of type
C, M, D, L, or N.

Files:

_DCASAVE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_hexstring2array()
   dc_ar2str()
   dc_asave()


dc_array2js()

Convert an array to JSON

DC_Array2JS() is used to convert an array to JSON (Javascript Object Notation). The array may contain any Xbase++ value including subarrays and objects. Only the iVars in the objects will be converted.

Syntax:

DC_Array2JS( <aArray> ) -> cJson

Returns:

A character string.

Arguments:

<aArray> is any multi-dimensional array.

See Also:

   dc_object2js()
   dc_array2xml()
   dc_object2xml()


dc_array2prg()

Save the contents of a multidimensional array to source code

DC_ARRAY2PRG() is used to create a .PRG file from the contents of a multi-dimensional array. This allows the programmer to capture the contents of any array to a source code file that can be compiled and run to rebuild the array.<br><br><br><br>

Syntax:

 DC_Array2Prg ( <aArray>, ;
                <cFileName>, ;
               [<cFunction>], ;
               [<cComments>], ;
               [<cCode>] ) -> lStatus

Returns:

 A logical .t. if the file was created.

Arguments:

<aArray> is the name of the array to write.

<cFileName> is the name of the file to create.

<cFunction> is the name of the function to call that will
return the array contents.  If this parameter is not passed
then the function will be given the same name as the file.

<cComments> is any comment heading to place at the top of
the file.

<cCode> is any source code that should be executed at the
beginning of the function before returning the array
contents.

Notes:

If the file being created already exists, then the user will be prompted to Append, Overwrite or Abort the operation.

Examples:

 -- Example 1 --

 . aMyArray := directory()
 . DC_ARRAY2PRG( aMyArray, "MYDIR" )
 . clip mydir  // compile mydir.prg
 . obj mydir   // load mydir.obj
 . aNewArray := MYDIR()

 -- Example 2 --

 . use all like cust*
 . browse tile       // configure browse windows
 . DC_ARRAY2PRG( DCBROWSE, 'MYBROWSE' )
 . clip mybrowse     // compile mbrowse.prg
 . obj mybrowse      // load mybrowse.obj
 . release dcbrowse  // kill old browse array
 . dcbrowse := MYBROWSE()

Files:

_DCARRAY.PRG, DCLIP1.DLL

See Also:

   dc_asave()


dc_array2sqlinsert()

Create SQL statement for inserting records

DC_Array2SQLInsert() is used to create a SQL statement for inserting records into a database. This accepts an 2-dimensional array that matches the order of fields or a 1-dimensional array of record objects.

Syntax:

DC_Array2SQLInsert( <aData>, <cTable> ) -> cSQLStatement

Returns:

A character string.

Arguments:

<aData> is a 2-dimensional array of values to write to the database
or a 1-dimensiona array of record objects to write to the database.

Notes:

This function is handy when processing a lot of transactions thatrequire adding many records to a database at one time. Normalappend() require locking and unlocking and also take a considerableamount of time. SQL INSERT, on the other hand, is very fastbecause everything is being done on the server. In additiona BEGIN TRANSACTION is put into the SQL at the beginning and aCOMMIT WORK at the end. This insures that no other task orworkstation can write to the database until all records areinserted.

Examples:

USE TRANS

aRecords := {}

oRecord := DC_DBRecord():new()
TRANS->(dbGoTo(0))

oRecord:date := Date()
...
oRecord:tran_type := 'LOGIN'

AAdd(aRecords,oRecord)

cSQL := DC_Array2SqlInsert(aRecords)

Files:

_DCSQL.PRG, DCLIPX.DLL

See Also:

   dc_adsstatement()


dc_array2xml()

Convert an array to XML

DC_Array2XML() converts an array to an XML string.

Syntax:

DC_Array2Xml( <aArray> ) -> cXML

Returns:

A character string.

Arguments:

<aArray> is any multi=dimensional array that includes any Xbase++
value including subarrays and objects.  Only the iVars of objects
are included in the XML.

Files:

_DCFUNCT.PRG

See Also:

   dc_object2xml()
   dc_array2js()
   dc_object2js()


dc_arrayview()

A Tree style array/object browser

DC_ARRAYVIEW() is used to browse multidimensional arrays and/or objects using a Tree-View style browser.<br><br> The array can be any type of array with any dimensions and may contain any type of data. When expanding the array tree, the user has the option of opening a new window to display the contents of the sub-tree. When expanding an object, the user has the option of displaying the properties of the object using DC_InspectObject().<br><br><br><br>

Syntax:

DC_ArrayView( <aArray> | <oObject>, ;
             [<lExpand>] ) -> nil

Returns:

 NIL.

Arguments:

<aArray> is any type of array.

<oObject> is any type of object.

<lExpand> if .TRUE. will expand the tree.  The default is .FALSE.

Examples:

 PROCEDURE XTest()

 LOCAL aDir

 aDir := directory()
 DC_ArrayView( aDir )

 RETURN

Files:

_DCARRAY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_inspectobject()


dc_asave()

Save a multidimensional array to a binary file

DC_ASAVE() will save the contents of any multi-dimensional array to a binary file for later restoring with DC_ARESTORE().<br><br> If the array contains code blocks, the code blocks will be saved and restored provide that they contain persistent data. Any code block that contains non-persistent data will be saved as a NIL.<br><br> If the array contains pointers to objects, they pointers will be saved as a NIL.<br><br>

Syntax:

DC_ASave ( <aArray>, ;
           <cFileName> ) -> lStatus

Returns:

 A logical .TRUE. if the array file was created, .FALSE.
 otherwise.

Arguments:

<aArray> is any multidimenstional array.

<cFileName> is the name of the binary file to create with
the array contents.

Examples:

 PROCEDURE XTest()

 LOCAL aDir1, aDir2

 DC_Gui(.t.)

 aDir1 := Directory()
 DC_ASAVE( aDir1, 'ADIR.ARX' )
 aDir2 := DC_Arestore( 'ADIR.ARX' )

 DC_Achoice( 5,10,20,30, DC_AConvert( aDir2 )[1] )

 RETURN

Files:

_DCASAVE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_arestore()
   SAVE ARRAY


dc_at_clear()

Clear all prompts added by DC_At_Prompt()

DC_AT_CLEAR() is used to clear the array that holds the menu prompts created with DC_AT_PROMPT(). This array is automatically cleared after calling DC_MENU_TO() so it is not necessary to call this function unless you wish to simply display menu prompts and not call the DC_MENU_TO() function to get a user selection.

Syntax:

DC_At_Clear() -> nil

Returns:

 NIL

Arguments:

 None

Examples:

 dc_at_prompt( 10, 10, "Open a File", "Use a new database" )
 DC_AT_CLEAR() // changed my mind

Files:

_DCMENU2.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_at_prompt()
   dc_menu_to()


dc_at_prompt()

A moused replacement for AT..PROMPT

DC_AT_PROMPT() is used with DC_MENU_TO() to replace Clipper @..PROMPT / MENU TO commands with a "mouseable" menu prompt system. The prompts and menu will behave exactly like the Clipper MENU TO system except the left button of the mouse will high-light the selected prompt, and the right button performs the same function as the <ENTER> key.

Syntax:

DC_At_Prompt( <nRow>, ;
              <nCol>, ;
              <cPrompt>, ;
              [<cMessage>] ) -> nil

Returns:

 NIL

Arguments:

<nRow> is the screen row to display the prompt.

<nCol> is the screen column to display the prompt.

<cPrompt> is the prompt to display on the screen.

<cMessage> is an optional message to display at the coordinates
defined by the SET MESSAGE environment variable or by the
message coordinates passed to DC_MENU_TO().

Examples:

 // display prompts
 DC_AT_PROMPT( 10, 10, "Open a File", "Use a new database" )
 DC_AT_PROMPT( 12, 10, "Open an Index", "Use an Index file" )
 DC_AT_PROMPT( 14, 10, "Edit database", "Browse all records" )

 // get a user selection and display message at row 20, col 25
 nChoice := dc_menu_to( 1, 20, 25 )

Files:

_DCMENU2.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_at_clear()
   dc_menu_to()


dc_atnext()

Find the next occurrence of a string in another string

DC_ATNEXT() is used to return the location of the nth occurence of a substring within a string.

Syntax:

DC_AtNext ( <cCharacter>, ;
            <cString>, ;
            <nOccurrence> ) -> nPosition

Returns:

 The numeric location of the <nOccurence> of <cCharacter> in
 <cString>.  If not found then 0 is returned.

Arguments:

<cCharacter> is the character or substring to search.

<cString> is the string to search.

<nOccurrence> is the occurrence of <cCharacter> in <cString> to
find.

Examples:

 PROCEDURE XTest()

 LOCAL cString

 DC_Gui(.t.)

 cString := 'this is a test'

 DC_MsgBox( { cString, ;
              DC_ATNEXT( 'is', cString, 1 ), ;
              DC_ATNEXT( 'is', cString, 2 ) } )

 RETURN

Files:

_DCATNXT.PRG/.OBJ, DCLIPX.LIB


dc_atoattr()

Convert a Clipper color string to a screen color attribute

DC_ATOATTR() is used to convert a Clipper color string to a numeric screen attribute. Screen attributes are represented as a number from 0 to 255 for a total of 256 colors. Clipper functions require that a color string be used for setting colors rather than a number.

Syntax:

DC_AtoAttr ( <cColorString> ) -> nColor

Returns:

 A character string.

Arguments:

<cColorString> is a valid Clipper color string.

Examples:

 PROCEDURE XTest()

 DC_Gui(.t.)

 DC_MsgBox( { DC_ATOATTR( 'R/GR' ), ;
              DC_ATOATTR( 'N/N' ), ;
              DC_ATOATTR( 'W+*/W' ) } )

 RETURN

Files:

_DCCOLOR.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_attrtoa()


dc_attrtoa()

Convert a screen color attribute to a color string

DC_ATTRTOA() is used to convert a screen attribute to a color string. Screen attributes are represented as a number from 0 to 255 for a total of 256 colors. Clipper functions require that a color string be used for setting colors rather than a number.

Syntax:

DC_AttrtoA ( <nColor> ) -> cColorString

Returns:

 A character string.

Arguments:

<nColor> is a number from 0 to 256.

Examples:

 PROCEDURE XTest()

 DC_Gui(.t.)

 DC_MsgBox( { DC_ATOATTR( 'R/GR' ), ;
              DC_ATOATTR( 'N/N' ), ;
              DC_ATOATTR( 'W+*/W' ) } )

 RETURN

Files:

_DCCOLOR.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_atoattr()


dc_autoresize()

Resize all objects to fit on the resized parent

DC_AutoReSize() is used to automatically resize and reposition all child objects so they use the real estate of the parent in the same proportions as the child objects before the parent was resized.<br><br>DC_AutoReSize() is designed to be placed in a code block that is attached to the :resize callback slot of the parent object.<br><br>The complete childlist tree is resized. <br><br>

Syntax:

DC_AutoReSize( <aOldSize>, ;
               <aNewSize>, ;
               <oParent>, ;
               <aGetList>, ;
               <lToolBars> ) -> nil

Returns:

 NIL.

Arguments:

<aOldSize> is a 2 element array containing the width and height
in pixels of the dialog window before resize.

<aNewSize> is a 2 element array containing the widht and height
in pixels of the dialog window after resize.

<oParent> is the parent object.

<aGetList> is the GetList array that was passed to DC_ReadGui().

<lToolBars> if .FALSE. will not resize DCTOOLBAR or XbpPushButton
objects.  These objects, if using bitmaps can truncate the image
when resized.  The position of the ToolBar or PushButton will
change accordingly but the size will not change.  The default
is .TRUE. (resize all toolbars and pushbuttons).

Notes:

DC_AutoReSize() will not resize or reposition anything on adialog that was painted with a Gra*() function or a DCGRA*command.

Due to a bug in Xbase++ 1.3 make sure to add o:hide() and o:show()to your resize code block or the screen may leave some undesirableside effects after resizing objects.

Examples:

FUNCTION XTest()

LOCAL GetList := {}, oDesc, oBrowse

USE COLLECT VIA DBFNTX

@ 12,0 DCSAY COLLECT->descrip SAYSIZE 50 ;
   SAYOBJECT oDesc COLOR GRA_CLR_BLUE FONT '12.Courier Bold'

@ .5,.5 DCBROWSE oBrowse ALIAS 'COLLECT' SIZE 49,9 ;
      EVAL {|o|o:itemMarked := {||oDesc:setCaption(COLLECT->descrip)} } ;
      HEADLINES 2 DELIMITER CHR(13)+CHR(10)

DCBROWSECOL FIELD COLLECT->descrip HEADER "Description"+CHR(13)+CHR(10)+"Line 2" ;
   PARENT oBrowse WIDTH 50

DCREAD GUI FIT ADDBUTTONS ;
   EVAL {|o| o:resize := ;
       {|a,b,o|DC_AUTORESIZE(a,b,o,GetList),o:hide(),o:show()} }

RETURN nil

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   DCGETOPTIONS


dc_autorestorebrowse()

Automatically Save/Restore Browse Configurations.

DC_AutoRestoreBrowse() is a Get-Set function that is used to Get/Set the Registry directory to be used for storing Browse column sizes and positions. Data is saved to the registry when a browse is destroyed and is restored from the registry when a browse is created.<br><br>If the user resizes columns and/or moves columns using the DC_XbpBrowse:moveColumn() method, then the information will be automatically saved to the registry for restoring later.<br><br>The name assigned to the item saved in the registry is the function name that contains the DCREAD GUI command concatenated with the ID of the DCBROWSE. This will insure that each name is unique (required).<br><br>Optionally, the window sizes and coordinates can be written to a file or a database by using a custom codeblock.

Syntax:

DC_AutoRestoreBrowse( [<aParams>] ) -> aOldParams

Returns:

An array of 2 elements.

Arguments:

<aParams> is a 2-element array.

Element Type Description
------- ---- ------------------------------------------------------
 [1]    N/B  The key value of the registry item to write.  The
             default is HKEY_LOCAL_MACHINE.

             The available options are defined in DCREG.CH.

             HKEY_NO_KEY
             HKEY_CLASSES_ROOT
             HKEY_CURRENT_USER
             HKEY_LOCAL_MACHINE
             HKEY_USERS

             Optionally, this element may contain a codeblock to evaluate.
             If this is a codeblock, then the registry will not be used.
             Instead, the codeblock is evaluated when saving or restoring
             the coordinate array.  When writing, 2 parameters are passed
             to the codeblock: (1) the window title and (2) the array of
             coordinates.  When reading, 1 parameter is passed to the
             codeblock () the window title.

 [2]    C    The entry name in the registry to store the information.
             This element is not used if Element 1 is a codeblock.

 [3]    L    Default Restore / NoRestore mode. If .TRUE. then the
             default for restoring windows is ON and the override clause
             of DCREAD GUI is NOAUTORESTORE.  If .FALSE., then the
             default for restoring windows will be OFF, and the override
             clause of DCREAD GUI is AUTORESTORE.

Notes:

The browse configuration will not be restored unless theDCBROWSE command is immediately followed by a set of DCBROWSECOLcommands in the GetList.

DCBROWSE commands must have a unique ID for this feature to beactivated. The ID must only be unique if there are multipleDCBROWSE windows in the same procedure or function.

Examples:

aParams := { HKEY_LOCAL_MACHINE, ;
             '\Software\Donnay Software\Xdemo\Browses' }

DC_AutoRestoreBrowse(aParams)

For more samples see \exp19\samples\autorestore.

Files:

_DCGETBX.PRG

See Also:

   @ DCBROWSE
   DC_AutoRestoreWindow()
   DC_RegWrite()
   DC_RegQuery()


dc_autorestorewindow()

Automatically Save/Restore window coordinates

DC_AutoRestoreWindow() is a Get-Set function that is used to Get/Set the Registry directory to be used for storing window sizes and coordinates. Data is saved to the registry when a window is closed and is restored from the registry when a window is created.<br><br>The name assigned to the item saved in the registry is the function name that contains the DCREAD GUI command concatenated with the title of the window. This will insure that each name is unique (required).<br><br>Optionally, the window sizes and coordinates can be written to a file or a database by using a custom codeblock.

Syntax:

DC_AutoRestoreWindow( [<aParams>] ) -> aOldParams

Returns:

An array of 2 elements.

Arguments:

<aParams> is a 3-element array.

Element Type Description
------- ---- ------------------------------------------------------
 [1]    N/B  The key value of the registry item to write.  The
             default is HKEY_LOCAL_MACHINE.

             The available options are defined in DCREG.CH.

             HKEY_NO_KEY
             HKEY_CLASSES_ROOT
             HKEY_CURRENT_USER
             HKEY_LOCAL_MACHINE
             HKEY_USERS

             Optionally, this element may contain a codeblock to evaluate.
             If this is a codeblock, then the registry will not be used.
             Instead, the codeblock is evaluated when saving or restoring
             the coordinate array.  When writing, 2 parameters are passed
             to the codeblock: (1) the window title and (2) the array of
             coordinates.  When reading, 1 parameter is passed to the
             codeblock () the window title.

 [2]    C    The entry name in the registry to store the information.
             This element is not used if Element 1 is a codeblock.

 [3]    L    Default Restore / NoRestore mode. If .TRUE. then the
             default for restoring windows is ON and the override clause
             of DCREAD GUI is NOAUTORESTORE.  If .FALSE., then the
             default for restoring windows will be OFF, and the override
             clause of DCREAD GUI is AUTORESTORE.

Notes:

The window size will not be restored if the NORESIZE clause ofDCGETOPTIONS was used when creating the window. Only the positionof the window will be restored.

Examples:

aParams := { HKEY_LOCAL_MACHINE, ;
             '\Software\Donnay Software\Xdemo\Windows' }

DC_AutoRestoreWindow(aParams)

For more samples see \exp19\samples\autorestore.

Files:

_DCGETBX.PRG

See Also:

   DC_AutoRestoreBrowse()
   DC_RegWrite()
   DC_RegQuery()


dc_availabledrives()

Returns a string of available logical drives

DC_AvailableDrives() returns a string containing the drive letters of all available logical drives.

Syntax:

DC_AvailableDrives() -> cDriveString

Returns:

A character string.

Arguments:

None.

Examples:

? DC_AvailableDrives()

ABCDEQRTV

Files:

_DCFUNCT.PRG, DCLIPX.DLL


dc_average()

Average numeric fields in selected database

DC_Average() is used to average numeric fields from the currently selected database based on a set of conditions. As GUI dialog window is displayed for the user to select the conditions.

Syntax:

 DC_Average() -> lStatus

Returns:

 A logical .TRUE. if the average was not aborted.

Arguments:

 None.

Examples:

 . USE COLLECT
 . DC_Average()

Files:

_DCSUM.PRG, DCLIP2.DLL

See Also:

   SUM


dc_basefont()

A Get-Set function for setting the Base Font for dialog objects

DC_BaseFont() is a Get-Set function that is used to set the base font for dialog items.<br><br>The default is 8.MS Sans Serif<br><br>

Syntax:

DC_BaseFont( [<nPointSize>], ;
             [<cFontName>], ;
             [<lBold>] ) -> <cFontCompoundName>

Arguments:

<nPointSize> is the point size.

<cFontName> is the font family name.

<lBold> if .TRUE. will set the font to bold.

Files:

_DCFUNCT.PRG, DCLIPX.DLL


dc_batch()

Process a Batch file with Dot-Prompt commands

DC_Batch() will execute all commands in a .DCB batch file in sequential order. A batch file can include any commands which can be entered at the dot-prompt and executed by the eXPress++ interpreter other than structural commands, like DO WHILE, DO CASE IF..ENDIF or FOR..NEXT. All commands in DCSTD.CH, DCDIALOG.CH, or DCCUSTOM.CH may be used in batch files.DC_BATCH() is used to open and execute a .DCB batch file. A "batch" file can contain any commands that can be interpreted at the dot prompt, including commands in .CH files which have been included in DCCUSTOM.CH.

Syntax:

dc_batch ( <cFileName>, ;
           [<c1>], ;
           [<c2>], ;
           [<c3>], ;
           [<c4>], ;
           [<c5>] ) -> nil

Returns:

 Nil.

Arguments:

<cFileName> is the name of the batch file to run.  If the
extension is not given then .DCB is assumed.

<c1> , <c2>, <c3>, <c4>, <c5> are optional parameters that are
received in the batch file via the PARAMETERS command.

Notes:

DC_Dot() will automatically execute an AUTOEXEC.DCB batch file found in the directory containing the executable program or the or the directory named by the dos SET DCLIP=<directory> environment setting.

Examples:

DC_BATCH('test.dcb',Date(),Time())    // run TEST.DCB file

* TEST.DCB

PARAMETERS dDate, cTime

FOR i := 1 TO 10
  DCQDEBUG dDate + i
NEXT

DCQDEBUG cTime

Files:

_dcbatch.prg, DCLIP1.DLL

See Also:

   BATCH
   dc_batchnewthread()


dc_batchnewthread()

Process a Batch file in a new thread

DC_BatchNewThread() functions identically to DC_Batch() except it will execute in a new thread.

Syntax:

DC_BatchNewThread ( <cFileName>, ;
                    [<c1>], ;
                    [<c2>], ;
                    [<c3>], ;
                    [<c4>], ;
                    [<c5>] ) -> nil

Returns:

 Nil.

Arguments:

<cFileName> is the name of the batch file to run.  If the
extension is not given then .DCB is assumed.

<c1> , <c2>, <c3>, <c4>, <c5> are optional parameters that are
subsituted by  %1 - %5 respectively in the batch file commands.

Notes:

DC_Dot() will automatically execute an AUTOEXEC.DCB batch file found in the directory containing the executable program or the or the directory named by the dos SET DCLIP=<directory> environment setting.

Examples:

. DC_BatchNewThread('test.dcb')    // run TEST.DCB file

Files:

_dcbatch.prg, DCLIP1.DLL

See Also:

   BATCH
   dc_batch()


dc_bin2num()

Converts a Binary String to a Number

DC_BIN2NUM() will convert a binary string to a numeric value.<br><br>

Syntax:

DC_Bin2Num( <cBinary> ) -> nDecimal

Returns:

 A numeric value from 0 - 255

Arguments:

<cBinary> is a string of up to eight 1's and 0's.

Files:

_DCAND.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_bittest()
   dc_xorbits()


dc_bitmapdraw()

Redraw a Bitmap Object on a GUI dialog screen

DC_BITMAPDRAW() is used to redraw a Bitmap object that was created with the DCBITMAP command and painted on a dialog screen with DC_READGUI().<br><br> This function is used to load a new *.BMP file into the presentation space previously created from the DCBITMAP object in the GetList.

Syntax:

DC_BitMapDraw ( <oParent>, ;
                <ncbResource> ) -> nil

Returns:

 Nil.

Arguments:

<oParent> is the Static object that contains the presentation
space for the bitmap.

<ncbResource> may be any of the following:

1. The number of a resource that has been linked to the .EXE

2. A character string with the name of a *.BMP file, a *.JPG file,
   a *.GIF file or a *.PNG file.

3. An XbpBitMap() object.

4. A code block which, when evaluated, returns a number, character
   string or XbpBitMap() object.

Examples:

 #include 'dcdialog.ch'

 PROCEDURE XTest()

 LOCAL GetList := {}, cBitMap1, cBitMap2, oPhoto1, oPhoto2

 USE COLLECT NEW SHARED
 SKIP 2

 cBitMap1 := COLLECT->bitmap1
 cBitMap2 := COLLECT->bitmap2

 @  2,2 DCSTATIC XBPSTATIC_TYPE_RAISEDBOX SIZE 33,10 ;
    OBJECT oPhoto1

 @  2,37 DCSTATIC XBPSTATIC_TYPE_RAISEDBOX SIZE 33,10 ;
    OBJECT oPhoto2

 DCBITMAP cBitMap1 PARENT oPhoto1 AUTOSCALE

 DCBITMAP cBitMap2 PARENT oPhoto2 AUTOSCALE

 @  1,3  DCSAY 'Photo 1' GET cBitMap1 ;
    SAYRIGHT SAYSIZE 10 ;
    DATALINK {||DC_BitMapDraw(oPhoto1,cBitMap1)}

 @  1,38 DCSAY 'Photo 2' GET cBitMap2 ;
    SAYRIGHT SAYSIZE 10 ;
    DATALINK {||DC_BitMapDraw(oPhoto2,cBitMap2)}

 DCREAD GUI ;
    FIT ;
    ADDBUTTONS

 RETURN

Files:

_DCFUNCT.PRG/.OBJ, DCLIPX.LIB

See Also:

   DCBITMAP
   dc_readgui()
   DIALOG GETLIST


dc_bitmapresourcefile()

Get-Set function used to set a list of resource DLLs for bitmaps

DC_BitmapResourceFile() is a Get-Set function that is used to establish a list of resource DLLs for finding bitmaps. All bitmaps in eXpress++ are loaded via the function DC_GetBitmap(). This function always returns a bitmap object of type XbpBitmap(). This function now runs through a loop to try to load resources from Dlls set with DC_BitmapResourceFile() if the named resource is not linked to the EXE, therefore bitmaps with a numeric resource ID can now be in multiple DLLs and do not need to be linked to the .EXE.<br><br>

Syntax:

DC_BitmapResourceFile( [<aDllList>] ) -> aOldDllList

Returns:

An array.

Arguments:

<aDllList> is an array of numeric DLL handles.

Examples:

nResDll1 := LoadDll('MYBITMAPS.DLL') // load my custom bitmaps
nResDll2 := LoadDll('DCRES.DLL')     // load eXpress++ bitmaps

DC_BitmapResourceFile( { nResDll1, nResDll2 } )

DCADDBUTTON CAPTION MYBITMAP_PERSON // defined in MYBITMAPS.DLL
DCADDBUTTON CAPTION BITMAP_HELP_M   // defined in DCRES.DLL

This eliminates the need to use the RESFILE clause when defined
bitmap captions.  Also, if the RESTYPE clause is not used, then
the resources must be of type BITMAP, GIF, JPEG, BMP or PNG in
your resource DLLs.

Files:

_DCGETBX.PRG/.OBJ, DCLIPX.DLL

See Also:

   dc_getbitmap()


dc_bitmaptransparentcolor()

Set RGB transparent color for pushbutton bitmaps

DC_BitmapTransparentColor() is a Get-Set function that is used to set the RGB value of the transparent color used with Bitmaps that are placed on DCPUSHBUTTON objects.<br><br>

Syntax:

DC_BitmapTransparentColor( [<anColor>] ) -> nOldColor

Returns:

A numeric value.

Arguments:

<anColor> is a 3-element array containing numeric RGB values or
an numeric equivalent of an RGB color.

Examples:

// set the transparent color to medium gray (the background
// color of the bitmaps)

aColor := { 192, 192, 192 }
DC_BitmapTransparentColor( aColor )

@ 0,0 DCPUSHBUTTON CAPTION DCBITMAP_FIND_1 SIZE 10,2
DCREAD GUI FIT

Files:

_DCGETBX.PRG, DCLIPX.DLL

See Also:

   @ DCPUSHBUTTON
   dc_getbitmap()


dc_bittest()

Tests if a bit is set to 1 or 0 in a number

DC_BITTEST() will test for a specified bit in a number.<br><br><br><br>

Syntax:

DC_BitTest( <nDecimal>, ;
            <nBit> ) -> lStatus

Returns:

 A logical .TRUE. if the bit is a 1 and a logical .FALSE. if
 the bit is a 0.

Arguments:

<nDecimal> is a numeric value from 0 to 255.

<nBit> is the bit to test.  This is a value from 1 to 8.

Files:

_DCAND.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_andbits()


dc_blank()

Blank all fields in the current record

DC_BLANK() is used to blank the contents of all fields in the current record of the current work area. It is not necessary to lock the record because DC_BLANK() will also lock and unlock the record before blanking the contents.

Syntax:

 DC_Blank( [<lCommit>] ) -> lStatus

Returns:

 A logical .TRUE. if the record was blanked.

Arguments:

<lCommit> if .TRUE. (default) will commit the changes to disk.

Examples:

 . USE COLLECT
 . GO 5
 . DC_Blank()

Files:

_dcblank.prg, DCLIP1.DLL

See Also:

   BLANK
   dc_isblank()


dc_bof()

Is the record pointer at the beginning of the file?

DC_BOF() is used to test whether or not DC_DbSkip() attempted to move the record pointer past the top record in a "scoped" set of records when using a negative skip value. If no scope is set or the ADSDBE is being used as the data driver for the current work area this function simply calls Bof() therefore it can be used as a replacement for Bof().<br><br>

Syntax:

 DC_Bof() -> lStatus

Returns:

 A logical value.

Arguments:

 None.

Notes:

Examples:

 DC_SetScope(0,'12001')
 DC_SetScope(1,'12001')

 DC_DbGoBottom()

 DO WHILE !DC_Bof()
   DC_DbSkip(-1)
 ENDDO

Files:

_DCSCOPE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_setscope()
   dc_eof()
   dc_dbskip()
   dc_dbgotop()
   dc_dbgobottom()


dc_browcelledit()

Edit Cells of a Browse Object

DC_BrowCellEdit() is used to edit the cells of any browse object. Navigation modes allow for moving up and down within the browse via the UP, DOWN keys or automatically moving DOWN or ACROSS with the ENTER key.<br><br> DC_BrowCellEdit() supports WHEN code blocks for each column to prevent the editing of a cell and VALID code blocks for each column to validate user input.<br><br> DC_BrowCellEdit() also is used to delete an element from the array being browsed or to insert and edit a new element.<br><br>

Syntax:

DC_BrowCellEdit( <oBrowse>, ;
                 [<nRow>],  ;
                 [<nCol>],  ;
                 [<nEditMode>],  ;
                 [<lArray>],  ;
                 [<abDefault>],  ;
                 [<bEval>]  ) -> nil

Arguments:

<oBrowse> is the browse object to edit, insert or delete.  This
must be an object of the XbpBrowse class.

<nRow> is the starting row.  If this argument is not passed,
then the currently selected row is the default.  <nRow> must
be a numeric value within the currently visible number of rows.

<nCol> is the starting column.  If this argument is not passed,
then the currently selected column is the default.  <nCol> must
be a numeric value between 1 and the total number of columns in
the browse object.

<nEditMode> is the editing and/or navigation mode.

 <nEditMode>             Description
 -----------             ---------------------------------------
 DCGUI_BROWSE_EDITEXIT   Edit - Exit cell editing after ENTER key
 DCGUI_BROWSE_EDITACROSS Edit - Move to next column after ENTER key
 DCGUI_BROWSE_EDITDOWN   Edit - Move to next row after ENTER key
 DCGUI_BROWSE_INSERT     Insert an element or a record
 DCGUI_BROWSE_DELETE     Delete current element or record

<lArray> is a logical value determining if the browsed data is an
array or a database.  If .TRUE., then it is an array.  If this
argument is not passed and the browse object was created via the
DCBROWSE command then this is determined automatically.  If an
array is being browsed, then the :cargo iVar of the browse object
must contain an array of at least 5 elements.  Element 5 is a
pointer to the array being browsed.  Element 4 is a numeric
value containing a pointer to the currently selected array
element.

<abDefault> is used only when inserting an array element, ie
<nMode> is DCGUI_BROWSE_INSERT.  This parameter contains either
an array or a code block which returns an array.  The array
contains the default data for the inserted element.  Note: array
browsers always browse multi-dimensional, symmetrical arrays, so
this array must contain the same number of sub-elements as each
array element.

<bEval> is an optional code block to evaluate before inserting,
deleting, or editing a cell row.

Notes:

The :dataLink iVar of each XbpColumn object in the XbpBrowse object is used to store the GET/SET code block for editing the cell. If the XbpColumn objects were created by the DCBROWSECOL command using the FIELD <cField> clause, then it will automatically be created as a GET/SET code block.

The :cargo iVar of each XbpColumn object in the XbpBrowse object may be used to store WHEN clause and VALID clause information. If the column objects were created by the DCBROWSECOL command then the code blocks for these clauses are automatically stored in XbpColumn:cargo. If the XbpColumn objects are NOT created by DCBROWSECOL, then you must store an array at least 7 elements in length into the XbpColumn:cargo instance variable.

XbpColumn:cargo[6] is used to store the VALID codeblock. This code block is used to validate the input for each column object. The value in the editing buffer of the cell is passed to the code block, therefore the code block should look like so:

{ |c| !Empty(c) }

The value passed is always the same type as the value of the field. The code block must return a logical value. If a .TRUE. is returned or the value stored in XbpColumn:cargo is not an array or the value stored in XbpColumn:cargo[6] is not a code block, then the value entered will be stored. If a .FALSE. is returned, then the editing window cannot be exited until a .TRUE. is returned or the ESCape key is pressed.

XbpColumn:cargo[7] is used to store the WHEN codeblock. This code block is used to prevent editing of a cell. It must always return a logical value. If a .TRUE. is returned or the value stored in XbpColumn:cargo is not an array or the value stored in XbpColumn:cargo[7] is not a code block, then the cell can be edited. If a .FALSE. is returned, then the cell will be skipped.

Examples:

 #include 'dcdialog.ch'

 PROCEDURE XTest()

 LOCAL GetList := {}, oBrowBox, oBrowse, oToolBar, GetOptions

 USE COLLECT NEW SHARED

 @  3,0 DCSTATIC XBPSTATIC_TYPE_RECESSEDBOX SIZE 78,12 ;
    OBJECT oBrowBox

 @ .1,.5 DCBROWSE oBrowse PARENT oBrowBox ALIAS 'COLLECT' ;
   SIZE 77,11.8

 DCBROWSECOL FIELD COLLECT->descrip ;
  HEADER "Description" PARENT oBrowse

 DCBROWSECOL FIELD COLLECT->type ;
  HEADER "Type" PARENT oBrowse

 DCBROWSECOL FIELD COLLECT->sub_type ;
  HEADER "SubType" PARENT oBrowse

 DCBROWSECOL FIELD COLLECT->location ;
  HEADER "Location" PARENT oBrowse

 DCBROWSECOL FIELD COLLECT->date_orig ;
  HEADER "Orig Date" PARENT oBrowse

 DCBROWSECOL FIELD COLLECT->date_acqu ;
  HEADER "Acqu Date" PARENT oBrowse

 DCTOOLBAR oToolBar

 DCADDBUTTON CAPTION 'Edit Down' ;
   SIZE 10 ;
   PARENT oToolBar ;
   ACTION {||DC_BrowCellEdit( oBrowse,,,DCGUI_BROWSE_EDITDOWN ) }

 DCADDBUTTON CAPTION 'Edit Across' ;
   PARENT oToolBar ;
   SIZE 10 ;
   ACTION {||DC_BrowCellEdit( oBrowse,,1,DCGUI_BROWSE_EDITACROSS ) }

 DCGETOPTIONS ;
   WINDOW WIDTH 560 ;
   WINDOW HEIGHT 350

 DCREAD GUI ;
   OPTIONS GetOptions ;
   ADDBUTTONS ;
   EVAL {||oBrowse:hide(), oBrowse:show()}

 RETURN

Files:

_DCGETBX.PRG, DCLIPX.LIB

See Also:

   @ DCBROWSE


dc_browcelleditexit()

Force an exit of the Browse Cell Editor

DC_BrowCellEditExit() is used in a cell editor validation clause to force an exit of the cell editor.<br><br>

Syntax:

 DC_BrowCellEditExit( [<nMode>] ) -> nOldMode

Returns:

 A numeric value.

Arguments:

<nMode> is the value to return from the Cell Editor event handler.
This should be either DCGUI_EXIT_ABORT or DCGUI_EXIT_OK.

DCGUI_EXIT_ABORT is the same as pressing the ESCAPE key.
DCGUI_EXIT_OK is the same as pressing the ENTER key.

Files:

_DCGETBX.PRG, DCLIPX.LIB

See Also:

   @ DCBROWSE
   dc_browcelledit()


dc_browpres()

A Get/Set function for browse presentation parameters.

DC_BrowPres() is a Get/Set function that is used to Get or Set a presentation parameters array for browse windows.<br><br>DC_BrowPres() returns a default set of browse paramaters if a user-defined set of parameters is not set.

Syntax:

DC_BrowPres([<aPres>, ;
            [<nFrame>]) -> aPres

Returns:

A presentation parameters array.

Arguments:

<aPres> is an array of browse presentation parameters that
conforms to the specification of parameters described in the
Xbase++ documentation for XbpBrowse().

<nFrame> is used to set the frame type for the hilighlight bar.
Each frame type is defined in DCDIALOG.CH as a DCGUI_BROWSEFRAME_*
constant.

Example: @ DCBROWSE .. PRESENTATION ;
           DC_BrowPres(,DCGUI_BROWSEFRAME_THICK_RECESSED)

Examples:

aBrowPres := ;
  { { XBP_PP_COL_HA_FGCLR, GRA_CLR_WHITE },            /* Header FG Color  */  ;
    { XBP_PP_COL_HA_BGCLR, GRA_CLR_DARKGRAY },         /* Header BG Color  */  ;
    { XBP_PP_COL_DA_ROWSEPARATOR, XBPCOL_SEP_DOTTED }, /* Row Sep          */  ;
    { XBP_PP_COL_DA_COLSEPARATOR, XBPCOL_SEP_DOTTED }, /* Col Sep          */  ;
    { XBP_PP_COL_DA_FGCLR, GRA_CLR_BLACK },            /* Row FG Color     */  ;
    { XBP_PP_COL_DA_BGCLR, GRA_CLR_WHITE },            /* Row BG Color     */  ;
    { XBP_PP_COL_DA_ROWHEIGHT, 16 },                   /* Row Height       */  ;
    { XBP_PP_COL_HA_HEIGHT, 10 },                      /* Header Height    */  ;
    { XBP_PP_HILITE_FGCLR, GRA_CLR_WHITE },            /* Hilite FG color  */  ;
    { XBP_PP_HILITE_BGCLR, GRA_CLR_DARKBLUE },         /* Hilite BG color  */  ;
    { XBP_PP_COL_FA_FGCLR, GRA_CLR_WHITE },            /* Footer FG Color  */  ;
    { XBP_PP_COL_FA_BGCLR, GRA_CLR_DARKGRAY },         /* Footer BG Color  */  ;
    { XBP_PP_COL_FA_HEIGHT, 10 }                       /* Footer Height    */  ;
  }

DC_BrowPres(aBrowPres)

@ 1,1 DCBROWSE oBrowse PRESENTATION DC_BrowPres()

Files:

_dcpres.prg

See Also:

   @ DCBROWSE


dc_browseautoseek()

Seek a record/array element based on a data entered into a GET

When browsing a database, DC_BrowseAutoSeek() is used to automatically seek to a record in a database that matches the text entered into a GET and refresh an associated browse object.<br><br>When browsing an array, DC_BrowseAutoSeek() is used to automatically seek to an element of the array that matches the text entered into a GET and refresh an associated browse object.<br><br>DC_BrowseAutoSeek() is intended to be used in a codeblock that is assigned to the :keyboard callback slot of a DCGET object or the GET portion of an @..DCSAY..GET object. It is also intended to be used with an @..DCBROWSE object.

Syntax:

DC_BrowseAutoSeek( <nKey>, ;
                   <oGET>, ;
                   <oBrowse>, ;
                   [<aData>], ;
                   [<nColumn>], ;
                   [<bcPrefix>], ;
                   [<bFormat>], ;
                   [<nSeekDelay>], ;
                   [<bSeek>], ;
                   [@<nPointer>] ) -> NIL

Returns:

 NIL.

Arguments:

<nKey> is the numeric value of the key pressed.

<oGET> is the DCGET object that is being used to enter the seek
string.

<oBrowse> is the @..DCBROWSE object that will be refreshed.

<aData> is the array being browsed.  If this parameter is not
used then it is assumed that a database is being browsed.

<nColumn> is the column element of the array to scan for a
match.  This parameter is used only with <aData> and is a
required parameter when browsing an array.

<bcPrefix> is the a value to insert at the beginning of the
seek string.  If a code block, then it must return a string.

<bFormat> is a seek string code block. The user input buffer
passed to this code block and the return value of code block
is used for the seek.

ex: {|c|Right(Space(7)+Alltrim(cString),7)}

<nSeekDelay> is the number of seconds after a key is pressed to
wait before performing the seek.  This allows a string to be
typed without performing a seek everytime a key is pressed.
The default is .1 seconds.

<bSeek> is a code block to use to do the actual seek.  If this
argument is not used then the function DC_DbSeek() will be used.
The code block will receive the keyboard buffer as an argument.
The code block must return a logical value - .TRUE. if record
was found, .FALSE. if not found.

@<nPointer> is a numeric variable (passed by reference) to store
the array element selected when the user double-clicks on the
browse or presses ENTER.  This value will be stored only when
using an array.

Notes:

When browsing a database, an index must be in focus and thekey of the index must match whatever is being entered by theuser into the GET.

The seek is a SOFTSEEK, meaning that the record that closelymatches the entered data will be selected.

When browsing an array the <nColumn> element of the array mustmatch whatever is being entered by the user into the GET.

Examples:

FUNCTION XTest

LOCAL GetList := {}, cSeek := Space(20), oBrowse

SET DEFA TO ..\XDOC
USE EXPRESS VIA FOXCDX EXCLUSIVE ALIAS 'XDOC'
SET INDEX TO EXPRESS.CDX
OrdSetFocus('COMMAND')
SET DEFA TO

@ 1,1 DCSAY 'Seek' GET cSeek SAYRIGHT PICT '@!' ;
      KEYBLOCK {|a,b,o|DC_BrowseAutoSeek(a,o,oBrowse)}

@ 3,1 DCBROWSE oBrowse ALIAS 'XDOC' SIZE 77,11.8

DCBROWSECOL FIELD XDOC->command HEADER "Command" PARENT oBrowse ;
  WIDTH 7

DCBROWSECOL FIELD XDOC->type  HEADER "Type" PARENT oBrowse ;
  WIDTH 6

DCBROWSECOL FIELD XDOC->category HEADER "Category" PARENT oBrowse ;
  WIDTH 6

DCBROWSECOL FIELD XDOC->short HEADER "Short Description" PARENT oBrowse

DCBROWSECOL FIELD XDOC->module HEADER "Module" PARENT oBrowse ;

DCBROWSECOL FIELD XDOC->see_also HEADER "See Also" PARENT oBrowse

DCBROWSECOL DATA {||XDOC->(recno())} HEADER "Record" PARENT oBrowse ;
  WIDTH 4

DCREAD GUI ;
    TITLE 'DC_BrowseAutoSeek() Demo' ;
    FIT ;
    ADDBUTTONS

RETURN nil

Files:

_DCFINDX.PRG, DCLIPX.DLL

See Also:

   @ DCBROWSE
   dc_findbrowse()


dc_browsecolor()

Set the default color for alternate rows of a DCBROWSE

DC_BrowseColor() is used to establish the default colors for alternate rows of all DCBROWSE objects. These colors will be invoked only if the COLOR clause of DCBROWSE is not used.<br><br><br><br>

Syntax:

DC_BrowseColor( [<aColors>] ) -> aOldColors

Returns:

An array.

Arguments:

<aColors> is an array of 4 colors.

Each color may be defined as a numeric value or a 3-element
array of RGB colors.

Element  Type  Description
-------  ----  -----------------------------------------------
   1      A/N  Odd row foreground color
   2      A/N  Odd row background color
   3      A/N  Even row foreground color
   4      A/N  Even row background color

Examples:

DC_BrowseColor( { nil, GRA_CLR_WHITE, nil, GRA_CLR_CYAN } )

Files:

_DCXBROW.PRG

See Also:

   @ DCBROWSE


dc_browsedb()

A text-based Database browsing system

DC_BROWSEDB() is a Multi-Window database browsing system that can be used as a complete menu-driven DBMS. DC_BROWSEDB() is the base system for all Text-Based browsing features. This is an array-driven system, ie, a multi-dimensional array ( DCBROWSE ) object is used to store all the parameters for all work areas.<br><br> DC_BROWSEDB() supports a complete set of menus and options: Edit, View, File, Search, Print, Utilities, etc. The text-based browse system supports the following features:<br><br> 1. Cut and Paste 2. Keyboard Macros 3. User-configuration 4. Multi-window browsing 5. Relational browsing 6. Sticky browsing 7. Pick-list operation<br><br> See the section titled BROWSE for a complete description of how to use the DC_BROWSEDB() function.<br><br>

Syntax:

DC_BrowseDb ( [<aOptions>], ;
              [<aFields>], ;
              [<cUdfName>], ;
              [<lExit>], ;
              [<lReSize>], ;
              [<lRestoreScreen>], ;
              [<cConfigFile>], ;
              [<lEditDb>], ;
              [<lProtect>], ;
              [<aMenu>], ;
              [<aKeys>], ;
              [<aMouse>], ;
              [<lBackGround>] ) -> Nil

Returns:

 Nil

Arguments:

<aOptions> is an array of parameters to define the size and
style of the browse window.

Element Type  Description
------- ---- ---------------------------------------------

 [ 1]    L   .t. - Pick-list operation.  Will only display
                   menu options for window configuration and
                   searching for a record.  Use this mode
                   when you want the user to choose a field
                   and/or record and exit with the RETURN key.
             .f. - Normal operation. (default).

 [ 2]    L   .t. - Protect data from being changed by user
             .f. - Allow data modification ( Default )

 [ 3]    N   Start Display Row  ( 0 is default )

 [ 4]    N   Start Display Column  ( 0 is default )

 [ 5]    N   End Display Row  ( 24 is default )

 [ 6]    N   End Display Column  ( 79 is default )

 [ 7]    L  .t. - Display File Data at bottom of window
            .f. - Don't Display File Data ( Default )

 [ 8]    L  .t. - Don't display a shadow around the window
            .f. - Display a shadow around window ( Default )

 [ 9]    L  .t. - Display a record number column ( Default )
            .f. - Don't display record numbers

 [10]    L  .t. - Set the TAB for this window ( Default )
            .f. - Don't set the TAB

 [11]    L  .t. - Automatic update of Relational Windows
            .f. - Don't update Relational Windows ( Default )

 [12]    L  .t. - One-To-Many Browse configuration
            .f. - Standard configuration ( Default )

 [13]    L  .t. - Sticky-Browse mode ON
            .f. - Sticky-Browse mode OFF ( Default )

 [14]    L  .t. - Display all child relational fields (Default)
            .f. - Don't display child fields

 [15]    L  .t. - Automatic update of Full-screen edit window
            .f. - Don't update Edit window (Default)

 [16]    L  .t. - Display a Record Tagging Column.

 [17]    N  Inkey value of keyboard key to use for record
            tagging with [16] is .TRUE.  Default is SPACE BAR
            (32)

 [18]    L  .t. - Fast Paint option.  Paints browse screens
                  faster if they contain long memo fields.  This
                  option will not display memo fields with the
                  capitalized "MEMO" when they are not empty.
            .f. - Display "MEMO" when memo fields are not empty
                  otherwise display "memo".  (Default)

 [19]    L  .t. - Display totals at the bottom of all numeric
                  columns.  This option can take a long time to
                  start-up the browse while totals are being
                  calculated.
            .f. - Don't display totals. (Default)

 [20]    L  .t. - Display menu bar at the top of the physical
                  screen (Row 0, Column 0)
            .f. - Display menu bar at the top of the browse
                  window (Default).

 [21]    L  .t. - PICK-EDIT mode.  In this mode, pressing the
                  ENTER key will exit the browse with the record
                  pointer at the selected record.  This is
                  different than PICK-LIST mode above, however,
                  because this option still allows editing by
                  selecting ADD or EDIT from the menus.
            .f. - ENTER key will edit currently selected field.

 [22]    L  .t. - AUTOSEEK mode. Overrides setting of Autoseek
                  that was saved in Browse configuration.

 [23]    C  Description of the Browse

 [24]    C  A list of relational browse windows separated by
            commas.

<aFields> is a 2-dimensional array of field names and headings.
If this argument is not passed, then all fields will appear in
the display with the field name used as the heading. There
should be one element in the second array for each element in
the first array.

 Example:

 { { 'CUST_NAME','CUST_NMBR','STREET1','CITY','STATE','ZIP' }, ;
   { 'Customer;Name','Number','Street','City','State','Zip' } }

 Note: Use semicolon (;) character(s) in the heading to break the
       heading display into multiple rows.

<cUdfName> is the name of a User-Defined Function to call
after each keystroke.

<lExit> if .TRUE. will paint the display and items on the
screen then return. .FALSE. is Default.

<lReSize> if .TRUE. will simply resize the browse window to
the new coordinates passed in <aOptions> and not affect the
previous browse configuration.

<lRestoreScreen> if .TRUE. (default) will restore the screen
upon exiting the browse, otherwise all the browse screens
will remain on the display.

<cConfigFile> is the name of a *.DBR file to use as the
browse configuration.  A *.DBR file is created by the
"Save Configuration to a File" selection from the FILES
menu after configuring the browse screen as desired.  If no
path is included in the file name, then the file must exist
in the same directory as the currently selected database.

<lEditDb> if .TRUE. will automatically paint a full-screen
EDIT window and update it every time the record pointer
changes in the browse window.  Use this parameter when you
want to see both a full-screen edit view and a browse view
at the same time.  Using this parameter is the same as
selecting "Automatic Update of Edit Window ON" from the
VIEW menu.  The default is .FALSE. or OFF.

<lProtect> if .TRUE. will protect the database from being
modified by the user.  The default is .FALSE.

<aMenu> is an optional array which is used to replace the
default Browse pull-down menus.  The menu array must conform
to the specification of the array returned by the
function DC_MENUEDIT() or DC_MENULOAD().  If <aMenu> is
a character string, then the string must contain the
NAME of the menu as contained in the menu dictionary file
(DCMENU.DBF).

<aKeys> is an optional array which is used to replace, add
or delete hot-keys from the Browse defaults.  The key array
must conform to the specification of the array returned by
the function DC_KEYEDIT() or DC_KEYLOAD().  If <aKeys> is
a character string, then the string must contain the
NAME of the key-set as contained in the key dictionary file
(DCKEY.DBF).

<aMouse> is an optional array which is used to add to the
default mouse-actions.  The mouse array must conform
to the specification of the array defined for use by the
function DC_MOUSEKEYS() or returned by the function
DC_MOUSEEDIT() or DC_MOUSELOAD().  If <aMouse> is a
character string, then the string must contain the
NAME of the mouse-set as contained in the mouse dictionary
file (DCMOUSE.DBF).

<lBackGround> if .TRUE. (default) will paint a default
background and all browse screens for all work areas.  If
.FALSE., then only the browse screen for the current work
area will be displayed over the existing screen.

Examples:

 use customer
 DC_BROWSEDB()
 use invoice new
 DC_BROWSEDB( { , , 0, 0, 24, 39 } )
 use invitems new
 set relation to inv_nmbr into invoice
 DC_BROWSEDB( { , , 0, 40, 24, 79, , , .t., .f., , .t., .t. } )

Files:

_DCBROW.PRG

See Also:

   BROWSE


dc_browsegetlist()

A Browse-view of a GetList array (for debugging)

DC_BrowseGetList() is used to browse an entire GetList array in a Multi-dimensional view. This utility helps in debugging dialogs.

Syntax:

DC_BrowseGetList( <aGetList> ) -> nil

Returns:

Nil.

Examples:

FUNCTION XTest()

LOCAL GetList[0], dDate := Date()

@ 0,0 DCSAY 'Enter Date' GET dDate

DCREAD GUI FIT ;
  EVAL {||DC_BrowseGetList(GetList)}

RETURN nil

Files:

DCLIP1.LIB, DCLIP1.DLL


dc_browserow()

Set or return the row (element) of a browse

DC_BrowseRow() is used to Get or Set the row of a browse object which was created by the @ DCBROWSE command. This function is used only when browsing arrays.<br><br>DC_BrowseRow() is used when it is necessary to seek an element of the array being browsed, then update the row pointer and refresh the browse.<br><br><br><br><br><br>

Syntax:

 DC_BrowseRow( <oBrowse>, ;
               [<nRow>] ) -> nRow

Returns:

 The numeric value of the current row (array element).

Arguments:

<oBrowse> is the browse object.

<nRow> is the element in the browse to select.

Examples:

#include 'dcdialog.ch'

FUNCTION XTest()

LOCAL GetList := {}, aDir := Directory(), oBrowse, aRef[2]

@ 0,0 DCBROWSE oBrowse SIZE 50,10 DATA aDir ;
   PRESENTATION DC_BrowPres() NOHSCROLL
DCBROWSECOL ELEMENT 1 HEADER 'File Name' WIDTH 15 PARENT oBrowse
DCBROWSECOL ELEMENT 2 HEADER 'File Size' WIDTH 13 PARENT oBrowse

DCREAD GUI FIT ADDBUTTONS ;
   HANDLER MyHandler REFERENCE aRef ;
   EVAL {|| aRef[1]:=oBrowse, aRef[2]:=aDir, ;
            SetAppFocus(oBrowse:getColumn(1)) }

RETURN nil

* -----------------

STATIC FUNCTION MyHandler( nEvent, mp1, mp2, oXbp, ;
                           oDlg, GetList, aRef )

LOCAL oBrowse := aRef[1], aDir := aRef[2], nFound

IF nEvent == xbeP_Keyboard
  nFound := ;
    AScan( aDir, {|a|Upper(Substr(a[1],1,1))==Upper(Chr(mp1))} )
  IF nFound > 0
    DC_BrowseRow( oBrowse, nFound )
    oBrowse:refreshAll()
  ENDIF
ENDIF

RETURN DCGUI_NONE

Files:

_DCGETBX.PRG, DCLIPX.LIB

See Also:

   @ DCBROWSE
   dc_getcolarray()


dc_browsesort()

Set Sort Header options for @..DCBROWSE

DC_BROWSESORT() is used to set the column heading options for @..DCBROWSE when using the sort feature that is activated by clicking in the header column.<br><br>

Syntax:

 DC_BrowseSort( [<aSortOptions>] ) -> aOldOptions

Returns:

An array containing the old sort options.

Arguments:

<aSortOptions> is an array of 6 elements.

Element    Description
------- -------------------------------------------------------
 1 / 2  Used to set the foreground and background color of the
        column heading that is chosen as the controlling sort
        order when clicking the mouse in the column heading.
        See the SORT clause of DCBROWSECOL.

 3 / 4  Used to set the foreground and background color of the
        column headings that are not the controlling sort order
        and are not selectable.  These columns will not change
        the sort order when the mouse is clicked in the header.

 5 / 6  Use to set the UP arrow and DOWN arrow bitmaps that are
        used in the column header of the sorted column when
        the order is "ascending" or "descending" respectively.

        NOTE: These are no longer used.  Instead, special Marlett
              font characters are used.

 7 / 8  Used to set the foreground and background color of the
        column headings that are not the controlling sort order
        but are selectable.  These columns will change the sort
        order when the mouse is clicked in the header.

Examples:

aSort := Array(6)

aSort[1] := GRA_CLR_WHITE // Sort Selected Color (Foreground)
aSort[2] := GRA_CLR_RED   // Sort Selected Color (Background)
aSort[3] := GRA_CLR_WHITE // Sort Non-Selectable Color (Foreground)
aSort[4] := GRA_CLR_DARKGRAY // Sort Non-Selectable Color (Background)
aSort[5] := nil
aSort[6] := nil
aSort[7] := GRA_CLR_WHITE // Sort Unselected Color (Foreground)
aSort[8] := GRA_CLR_BLUE  // Sort Unselected Color (Background)
aSaveSort := DC_BrowseSort(aSort)

@ 10,1 DCBROWSE oBrowse

DCREAD GUI

DC_BrowseSort(aSaveSort)

Files:

_DCXBROW.PRG, DCLIPX.DLL

See Also:

   @ DCBROWSE


dc_busyoff()

Destroy a busy window created with DC_BusyOn()

DC_BusyOn() is used to embed a dialog window into another dialog window to provide a means to display a "busy" message and to temporarily disable the drawing area of the parent window during a process. DC_BusyOff() is used to destroy the temporary child window.<br><br>

Syntax:

DC_BusyOff( <oBusyDlg> ) -> nil

Arguments:

<oBusyDlg> is a pointer to a dialog window created by
DC_BusyOn().

Examples:

FUNCTION XTest()

LOCAL lContinue := .t.

oBusyDlg := DC_BusyOn( SetAppWindow(), ;
                       {||WaitDialog(@lContinue,@oStatus)} )

DO WHILE !Eof() .AND. lContinue

  oStatus:setCaption('Processing Record ' + Alltrim(Str(n)))
  SKIP
  DC_CompleteEvents()

ENDDO

DC_BusyOff(oBusyDlg)

RETURN nil

* -------------------

STATIC FUNCTION WaitDialog( lContinue, oStatus )

LOCAL GetList[0], oBusyDlg, GetOptions

@ 0,0 DCSAY "Processing" FONT '20.Arial Bold' SAYSIZE 0

@ 2,0 DCSAY '' OBJECT oStatus COLOR GRA_CLR_BLUE FONT '12.Arial Bold' SIZE 30

@ 4,8 DCPUSHBUTTON CAPTION 'Cancel' ACTION {||lContinue := .F. } SIZE 9, 1.2

DCGETOPTIONS NOTITLEBAR HIDE

DCREAD GUI FIT EXIT PARENT @oBusyDlg OPTIONS GetOptions

RETURN oBusyDlg

Files:

_DCMSG.PRG, DCLIPX.DLL

See Also:

   dc_waiton()


dc_busyon()

Invoke a busy message window

DC_BusyOn() is used to embed a dialog window into another dialog window to provide a means to display a "busy" message and to temporarily disable the drawing area of the parent window during a process. DC_BusyOff() is used to destroy the temporary child window.<br><br>

Syntax:

DC_BusyOn( <oParentDlg>, ;
           <bDialog> ) -> oBusyDlg

Returns:

A pointer to a dialog window object.

Arguments:

<oParentDlg> is a pointer to any window derived from the
XbpDialog() class.  This is the window who's drawing area will
be disabled and which will be come the parent of the child
window.

<bDialog> is a code block to evaluate.  The code block must
return a dialog window which will be embedded within <oParentDlg>.

Examples:

FUNCTION XTest()

LOCAL lContinue := .t.

oBusyDlg := DC_BusyOn( SetAppWindow(), ;
                       {||WaitDialog(@lContinue,@oStatus)} )

DO WHILE !Eof() .AND. lContinue

  oStatus:setCaption('Processing Record ' + Alltrim(Str(n)))
  SKIP
  DC_CompleteEvents()

ENDDO

DC_BusyOff(oBusyDlg)

RETURN nil

* -------------------

STATIC FUNCTION WaitDialog( lContinue, oStatus )

LOCAL GetList[0], oBusyDlg, GetOptions

@ 0,0 DCSAY "Processing" FONT '20.Arial Bold' SAYSIZE 0

@ 2,0 DCSAY '' OBJECT oStatus COLOR GRA_CLR_BLUE FONT '12.Arial Bold' SIZE 30

@ 4,8 DCPUSHBUTTON CAPTION 'Cancel' ACTION {||lContinue := .F. } SIZE 9, 1.2

DCGETOPTIONS NOTITLEBAR HIDE

DCREAD GUI FIT EXIT PARENT @oBusyDlg OPTIONS GetOptions

RETURN oBusyDlg

Files:

_DCMSG.PRG, DCLIPX.DLL

See Also:

   dc_waiton()


dc_byteshift()

Shift a byte a specified number of bits

DC_ByteShift() is used to shift the bits in a byte a specified amount.<br><br>

Syntax:

DC_ByteShift( <cChar>, ;
              [<nShift>] ) -> cChar

Returns:

 A character (byte).

Arguments:

<cChar> is any character (byte).

<nShift> is the number of bits to shift from -7 to +7.

Files:

_DCAND.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_bin2num()
   dc_num2word()


dc_calcabsoluteposition()

Calculate desktop position from an objects coordinates

DC_CalcAbsolutePosition() returns the coordinates of an object with respect to coordinate 0,0 of the desktop. This is needed to get coordinates for tooltips and modal popup windows that must be displayed adjecent to another object.

Syntax:

DC_CalcAbsolutePosition( [<aPos>], <oXbp> ) -> aCoords

Returns:

A two element array containing two numeric values:

1. The absolute COLUMN position.
2. The absolute ROW position.

Arguments:

<aPos> is a two-element array containing the offset from the
object for the resultant output.  The default is {0,0}.

<oXbp> is the object whose absolute coordinates are being
calcualated.

Examples:

// This function will center an object on the screen over any
// relative object.

FUNCTION DC_CenterObject( oXbp, oRel )

LOCAL nRelWidth, nRelHeight, nWidth, nHeight, nCol, nRow, aPos

DEFAULT oRel := oXbp:setParent()

nWidth := oXbp:currentSize()[1]
nHeight := oXbp:currentSize()[2]
nRelWidth := oRel:currentSize()[1]
nRelHeight := oRel:currentSize()[2]
nCol := (nRelWidth-nWidth)/2
nRow := (nRelHeight-nHeight)/2

IF oRel == oXbp:setParent()
  oXbp:setPos( {nCol,nRow} )
ELSE
  aPos := DC_CALCABSOLUTEPOSITION({0,0},oRel)
  oXbp:setPos( {aPos[1]+nCol,aPos[2]+nRow} )
ENDIF

RETURN nil

Files:

_DCFUNCT.PRG, DCLIPX.DLL


dc_callstack()

Display the callstack and optionally edit the source

DC_CallStack() is used to display a GUI dialog listing the current call stack and line numbers.<br><br> Clicking on an item in the list will scan the list of .OBJs in the ODIR path to find the source of the function. If the same named function exists in more than one .OBJ, then all .OBJs will be listed. Clicking on the selected .OBJ will call the default editor and pass the name and line number of the selected source file to editor for editing.<br><br>

Syntax:

 DC_CallStack() -> Nil

Returns:

 Nil.

Arguments:

 None.

Examples:

 . DC_SetKeyActive(.t.)
 . SetKey( K_ALT_S, {||DC_CallStack()} )

Files:

_DCOFIND.PRG, DCLIP2.DLL

See Also:

   STACK
   dc_editprg()
   dc_objpublic()


dc_capfirst()

Capitalize the first character of each word.

DC_CapFirst() capitalizes the first letter of all words in a string and leaves all other letters lowercase.

Syntax:

DC_CapFirst( <cString>, ;
             [<lLower>] ) -> cString

Returns:

A Character String.

Arguments:

<cString> is any string.

<lLower> if .TRUE. will force all characters except the first
character in each word to lower case.  The default is .FALSE.

Examples:

. ? DC_CapFirst('DONNAY SOFTWARE DESIGNS',.t.)
Donnay Software Designs

. ? DC_CapFirst('donnay SoftWare')
Donnay SoftWare

Files:

_DCCAPF.PRG, DCLIP1.DLL


dc_cascadecoords()

Returns coordinates to cascade a window

DC_CASCADECOORD() returns an array of two coordinates. These coordinates are calculated by scanning the childlist of an object and finding the object with the lowest coordinates. This allows for cascading of dialog windows.

Syntax:

DC_CascadeCoords( [<oParent>], ;
                  [<lTextBased>], ;
                  [<aDefault>], ;
                  [<lTranslate>], ;
                  [<oExclude>] ) -> aCoords

Returns:

 An array of two numeric coordinates:

 Element 1 is the row.
 Element 2 is the column.

Arguments:

<oParent> is the dialog window to scan.  If no parameter is
passed the AppDeskTop() is the default.

<lTextBased> will return text-based coordinates if .TRUE.
otherwise it will return pixel-based coordinates (default).

<aDefault> is an array of two coordinates to return if no
siblings were found.

<lTranslate> if .TRUE. (default) will return coordinates
translated with 0,0 at the top of the parent window.  If
.FALSE. the coordinates will be relative to 0,0 at the bottom
of the parent window.

<oExclude> is a sibling object (an object in the childlist) to
ignore when scanning the childlist.

Examples:

/*
This example will set the coordinates of a dialog window to
cascaded coordinates relative to the lowest sibling on the
desktop.  If there are no siblings, the current coordinates
will be used.
*/

FUNCTION Xtest( oDlg )

LOCAL aCoords, nRow, nCol

nRow := oDlg:currentPos()[2]
nCol := oDlg:currentPos()[1]

aCoords := ;
  DC_CascadeCoords(AppDesktop(),.f.,{nRow,nCol},.f.,oDlg)

oDlg:setPos( { nCol, nRow } )

RETURN nil

Files:

_DCFUNCT.PRG, DCLIPX.LIB


dc_cdow()

Translated name of the Day of Week

DC_CDow() is used to get the name of the day of the week for a specified date. The name is translated to the language previously selected by DC_LangSel().

Syntax:

DC_CDow( <dDate> ) -> cDayOfWeek

Returns:

A character string.

Arguments:

<dDate> is any valid date type.

Examples:

DC_LangSet( DCLANG_GERMAN )
? DC_CDow( Date() )
Mittwoch

Files:

_DCCALEN.PRG, DCLIPX.DLL

See Also:

   dc_cmonth()
   dc_langset()
   dc_langmsg()


dc_celledittimeout()

Set a timeout for the Cell-Editor

DC_CellEditTimeOut() is used to establish a timeout to exit the cell editor if there is no user activity after a specified amount of time.<br><br> The Cell Editor automatically locks the record and holds the lock until it exits or until a new record is selected. If the user enters the cell-editor and walks away from the computer, a lock on the record for a long period of time may be undesirable.<br><br>

Syntax:

 DC_CellEditTimeOut( [<nSeconds>] ) -> nOldTimeOut

Returns:

 A numerical value equivalent to the previous timeout setting.

Arguments:

<nSeconds> is the amount of time, in seconds, to allow cell-
editing with no user activity.  The default is 0 (no time out).

Files:

_DCGETBX.PRG, DCLIPX.LIB

See Also:

   dc_browcelledit()


dc_centerobject()

Center an Object

DC_CENTEROBJECT() will center any object within the viewing area of it's parent object or any other object.

Syntax:

DC_CenterObject ( <oXbp>, ;
                  [<oReference>] ) -> nil

Returns:

 nil

Arguments:

<oXbp> is the object to center.

<oReference> is the reference object to center <oXbp> in.
If <oReference> is not passed, <oXbp> will be centered within it's
parent.

Examples:

 -- Example 1 --

 * Center the CRT window on the Desktop

 DC_CenterObject(SetAppWindow(),AppDeskTop())

Files:

_DCFUNCT.PRG/.OBJ, DCLIPX.LIB


dc_cgigetenvval()

Read an environment variable in a CGI program

DC_CGIGetEnvVal() is used to get the value of an environment variable that has been passed by an HTML form to a CGI application. When a CGI application starts, DC_CGIInit() stores all the passed environment variables to a static array which is accessed by DC_CGIGetEnvVal().

Syntax:

 DC_CGIGetEnvVal( <nEnvName> ) -> cValue

Returns:

 A character string.

Arguments:

<nEnvName> is the numeric value defined in DCCGI.CH.  The
following names are available.

AUTH_TYPE
CONTENT_LENGTH
CONTENT_TYPE
GATEWAY_INTERFACE
HTTP_USER_AGENT
HTTP_ACCEPT
HTTP_FROM
PATH_INFO
PATH_TRANSLATED
QUERY_STRING
REFERER_URL
REMOTE_ADDR
REMOTE_HOST
REMOTE_IDENT
REMOTE_USER
REQUEST_METHOD
SCRIPT_NAME
SERVER_NAME
SERVER_PORT
SERVER_PROTOCOL
SERVER_SOFTWARE
SERVER_ADMIN
GMT_OFFSET
HTTP_REFERRER
HTTP_COOKIE
_FROM
AUTH_NAME
DATE_LOCAL
CONTENT_STRING
REQUEST_PROTOCOL
EXECUTABLE_PATH
KEEP_ALIVE
DOC_ROOT
AUTH_PASSWORD
AUTH_METHOD
AUTH_REALM
DEBUG_MODE
X_SERIAL_NUMBER
PRAGMA
ACCEPT_LANGUAGE
HOST
UA_PIXELS
UA_COLOR
UA_OS
UA_CPU
EXTENSION
CGI_VERSION
NT_USERNAME
OUTPUT_FILE
CONTENT_FILE

Notes:

DC_CGIInit() must be called before using this function.

Variables passed to a CGI program are always character strings.

Examples:

<form METHOD="POST" ACTION="/cgi-bin/waa1gate.exe?dummy=0">

     Your Name <input NAME="Name" TYPE="TEXT" size="20">
       Company <input NAME="Company" TYPE="TEXT" size="20">
       Street1 <input NAME="Street1" TYPE="TEXT" size="20">
       Street2 <input NAME="Street2" TYPE="TEXT" size="20">
          City <input NAME="City" TYPE="TEXT" size="20">
         State <input NAME="State" SIZE="10" TYPE="TEXT">
           Zip <input NAME="Zip" TYPE="TEXT" SIZE="10">
       Country <input NAME="Country" TYPE="TEXT" size="20">
E-Mail Address <input NAME="Email" TYPE="TEXT" size="20">
         Phone <input NAME="Phone" TYPE="TEXT" size="20">
           Fax <input NAME="Fax" TYPE="TEXT" size="20">

<input type=hidden name="WAA_PACKAGE" value="DS">
<input type=hidden name="WAA_FORM" value="FreeDownload">
<input type=SUBMIT name="FreeDownload" value="Download!"
</form>

FUNCTION _register( oPackage )

oPackage:registerForm( 'FreeDownload' )

RETURN .T.

* -----------------

FUNCTION FreeDownload( oHtml, oContext )

IF !DC_CGIInit(oHtml, oContext)
  RETURN .f.
ENDIF

// send the environment back to the browser

FOR i := 1 to 50
  DC_CGISend( DC_CGIGetEnvVal(i) )
NEXT

RETURN

Files:

_DCCGI.PRG, DCLIPX.DLL

See Also:

   dc_cgigetparmval()
   dc_cgiinit()


dc_cgigetparmval()

Read a data variable in a CGI program

DC_CGIGetParmVal() is used to get the value of a data variable that has been passed by an HTML form to a CGI application. When a CGI application starts, DC_CGIInit() stores all the passed data variables to a static array which is accessed by DC_CGIGetParmVal().

Syntax:

 DC_CGIGetParmVal( <cVarName>, ;
                   [@<cValue>], ;
                   [<oHtml>] ) -> cValue

Returns:

 A character string.

Arguments:

<cVarName> is the case sensitive name of the variable holding
the value.

@<cValue> is the name of a variable, passed by reference, to
store the value.

<oHtml> is the HTML3 object passed to the program.  If this
parameter is not used then the HTML3 object posted by the
DC_CGIInit() function will be used.  CAUTION: When running
heavily loaded CGI programs that may receive simultaneous hits
it is recommended that this parameter be used.

Notes:

DC_CGIInit() must be called before using this function.

Variables passed to a CGI program are always character strings.

Examples:

<form METHOD="POST" ACTION="/cgi-bin/waa1gate.exe?dummy=0">

     Your Name <input NAME="Name" TYPE="TEXT" size="20">
       Company <input NAME="Company" TYPE="TEXT" size="20">
       Street1 <input NAME="Street1" TYPE="TEXT" size="20">
       Street2 <input NAME="Street2" TYPE="TEXT" size="20">
          City <input NAME="City" TYPE="TEXT" size="20">
         State <input NAME="State" SIZE="10" TYPE="TEXT">
           Zip <input NAME="Zip" TYPE="TEXT" SIZE="10">
       Country <input NAME="Country" TYPE="TEXT" size="20">
E-Mail Address <input NAME="Email" TYPE="TEXT" size="20">
         Phone <input NAME="Phone" TYPE="TEXT" size="20">
           Fax <input NAME="Fax" TYPE="TEXT" size="20">

<input type=hidden name="WAA_PACKAGE" value="DS">
<input type=hidden name="WAA_FORM" value="FreeDownload">
<input type=SUBMIT name="FreeDownload" value="Download!"
</form>

FUNCTION _register( oPackage )

oPackage:registerForm( 'FreeDownload' )

RETURN .T.

* -----------------

FUNCTION FreeDownload( oHtml, oContext )

LOCAL cName, cStreet1, cStreet2, cCompany, ;
      cEmail, cState, cZip, cPhone, cFax, cCountry, cCity

IF !DC_CGIInit(oHtml, oContext)
  RETURN .f.
ENDIF

dbeSetDefault('DBFCDX')

cName := DC_CGIGetParmVal('Name')
cCompany := DC_CGIGetParmVal('Company')
cStreet1 := DC_CGIGetParmVal('Street1')
cStreet2 := DC_CGIGetParmVal('Street2')
cState := DC_CGIGetParmVal('State')
cZip := DC_CGIGetParmVal('Zip')
cEmail := DC_CGIGetParmVal('Email')
cCountry := DC_CGIGetParmVal('Country')
cCity := DC_CGIGetParmVal('City')
cPhone := DC_CGIGetParmVal('Phone')
cFax := DC_CGIGetParmVal('Fax')

IF Empty(cName) .OR. !'@'$cEmail

  oHTML:message( "Error", ;
  'Please provide a Name and E-mail Address.<p>' + ;
  'Click on your Back Button to return to the download page.<p>')
  DC_CGIQuit()
  RETURN .t.

ELSE

  USE register INDEX register.cdx
  OrdSetFocus('EMAIL')
  SEEK Upper(Alltrim(cEmail))
  IF Eof() .AND. DC_AddRec(10)
    REPL REGISTER->name WITH cName,;
         REGISTER->company WITH cCompany,;
         REGISTER->street1 WITH cStreet1,;
         REGISTER->street2 WITH cStreet2,;
         REGISTER->city WITH cCity,;
         REGISTER->country WITH cCountry,;
         REGISTER->state WITH cState,;
         REGISTER->zip WITH cZip,;
         REGISTER->phone WITH cPhone,;
         REGISTER->fax WITH cFax,;
         REGISTER->email WITH cEmail,;
         REGISTER->filename WITH cVariable,;
         REGISTER->date WITH Date(),;
         REGISTER->time WITH Time()
     UNLOCK
   ENDIF

   RunShell('/C C:\spimail\sm.exe /t:' + Alltrim(cEmail) + ;
            ' /s:"File Download Instructions"' + ;
            ' /m:' + MemoRead('download.txt',,.t.,.t. )

   cHtml += 'An email message has been sent to <em><b>' + Alltrim(cEmail) + ;
            ' </b></em>with download instructions<br><br>'

  DC_CGISend(cHtml)

ENDIF

RETURN

Files:

_DCCGI.PRG, DCLIPX.DLL

See Also:

   dc_cgiinit()


dc_cgiinit()

Initialize CGI environment

DC_CGIInit() is used in Web applications designed for use with the WAA (Web Application Adapter). This function reads all the passed environment variables and data variables into static arrays for later access with DC_CGIGetParmVal(). <br><br> DC_CGIInit() also creates (an overwrites) two text files:<br><br> CGIVARS.TXT - Contains a list of all data variables. CGIENVIR.TXT - Contaisn a list of all environment variables.<br><br> Note: These files are overwritten each time DC_CGIInit() is run in a program. They are intended to be used for debugging problems immediately after they occur.

Syntax:

 DC_CGIInit( <oHtml>, ;
             <oContext> ) -> lStatus

Returns:

 A logical .TRUE. if the environment was properly initialized,
 .FALSE. otherwise.

Arguments:

<oHtml> is the HTML3 object passed by the WAA adapter to the
application.

<oContext> is the Context object passed by the WAA adapter to
the application.

Notes:

This must be the first DC_CGI*() function called in a WAA program.

Examples:

<form METHOD="POST" ACTION="/cgi-bin/waa1gate.exe?dummy=0">

     Your Name <input NAME="Name" TYPE="TEXT" size="20">
       Company <input NAME="Company" TYPE="TEXT" size="20">
       Street1 <input NAME="Street1" TYPE="TEXT" size="20">
       Street2 <input NAME="Street2" TYPE="TEXT" size="20">
          City <input NAME="City" TYPE="TEXT" size="20">
         State <input NAME="State" SIZE="10" TYPE="TEXT">
           Zip <input NAME="Zip" TYPE="TEXT" SIZE="10">
       Country <input NAME="Country" TYPE="TEXT" size="20">
E-Mail Address <input NAME="Email" TYPE="TEXT" size="20">
         Phone <input NAME="Phone" TYPE="TEXT" size="20">
           Fax <input NAME="Fax" TYPE="TEXT" size="20">

<input type=hidden name="WAA_PACKAGE" value="DS">
<input type=hidden name="WAA_FORM" value="FreeDownload">
<input type=SUBMIT name="FreeDownload" value="Download!"
</form>

FUNCTION _register( oPackage )

oPackage:registerForm( 'FreeDownload' )

RETURN .T.

* -----------------

FUNCTION FreeDownload( oHtml, oContext )

LOCAL cName, cStreet1, cStreet2, cCompany, ;
      cEmail, cState, cZip, cPhone, cFax, cCountry, cCity

IF !DC_CGIInit(oHtml, oContext)
  RETURN .f.
ENDIF

dbeSetDefault('DBFCDX')

cName := DC_CGIGetParmVal('Name')
cCompany := DC_CGIGetParmVal('Company')
cStreet1 := DC_CGIGetParmVal('Street1')
cStreet2 := DC_CGIGetParmVal('Street2')
cState := DC_CGIGetParmVal('State')
cZip := DC_CGIGetParmVal('Zip')
cEmail := DC_CGIGetParmVal('Email')
cCountry := DC_CGIGetParmVal('Country')
cCity := DC_CGIGetParmVal('City')
cPhone := DC_CGIGetParmVal('Phone')
cFax := DC_CGIGetParmVal('Fax')

IF Empty(cName) .OR. !'@'$cEmail

  oHTML:message( "Error", ;
  'Please provide a Name and E-mail Address.<p>' + ;
  'Click on your Back Button to return to the download page.<p>')
  DC_CGIQuit()
  RETURN .t.

ELSE

  USE register INDEX register.cdx
  OrdSetFocus('EMAIL')
  SEEK Upper(Alltrim(cEmail))
  IF Eof() .AND. DC_AddRec(10)
    REPL REGISTER->name WITH cName,;
         REGISTER->company WITH cCompany,;
         REGISTER->street1 WITH cStreet1,;
         REGISTER->street2 WITH cStreet2,;
         REGISTER->city WITH cCity,;
         REGISTER->country WITH cCountry,;
         REGISTER->state WITH cState,;
         REGISTER->zip WITH cZip,;
         REGISTER->phone WITH cPhone,;
         REGISTER->fax WITH cFax,;
         REGISTER->email WITH cEmail,;
         REGISTER->filename WITH cVariable,;
         REGISTER->date WITH Date(),;
         REGISTER->time WITH Time()
     UNLOCK
   ENDIF

   RunShell('/C C:\spimail\sm.exe /t:' + Alltrim(cEmail) + ;
            ' /s:"File Download Instructions"' + ;
            ' /m:' + MemoRead('download.txt',,.t.,.t. )

   cHtml += 'An email message has been sent to <em><b>' + Alltrim(cEmail) + ;
            ' </b></em>with download instructions<br><br>'

  DC_CGISend(cHtml)

ENDIF

RETURN

Files:

_DCCGI.PRG, DCLIPX.DLL

See Also:

   dc_cgigetparmval()
   dc_cgigetenvval()


dc_cginocrsend()

Send data to the web browser without a CR

DC_CGINoCrSend() is used to send HTML data to the web browser without adding a CR (Chr(13)) to the response.

Syntax:

 DC_CGINoCrSend( <cHTML>, [<oHtml>] ) -> nil

Returns:

 Nil.

Arguments:

<cHTML> is any HTML response.  The text will be added to any
previous calls to DC_CGISend() in the program and all text
will be sent when the program terminates.

<oHtml> is the HTML3 object passed to the program.  If this
parameter is not used then the HTML3 object posted by the
DC_CGIInit() function will be used.  CAUTION: When running
heavily loaded CGI programs that may receive simultaneous hits
it is recommended that this parameter be used.

Notes:

This must be the first DC_CGI*() function called in a WAA program.

Examples:

<form METHOD="POST" ACTION="/cgi-bin/waa1gate.exe?dummy=0">

     Your Name <input NAME="Name" TYPE="TEXT" size="20">
       Company <input NAME="Company" TYPE="TEXT" size="20">
       Street1 <input NAME="Street1" TYPE="TEXT" size="20">
       Street2 <input NAME="Street2" TYPE="TEXT" size="20">
          City <input NAME="City" TYPE="TEXT" size="20">
         State <input NAME="State" SIZE="10" TYPE="TEXT">
           Zip <input NAME="Zip" TYPE="TEXT" SIZE="10">
       Country <input NAME="Country" TYPE="TEXT" size="20">
E-Mail Address <input NAME="Email" TYPE="TEXT" size="20">
         Phone <input NAME="Phone" TYPE="TEXT" size="20">
           Fax <input NAME="Fax" TYPE="TEXT" size="20">

<input type=hidden name="WAA_PACKAGE" value="DS">
<input type=hidden name="WAA_FORM" value="FreeDownload">
<input type=SUBMIT name="FreeDownload" value="Download!"
</form>

FUNCTION _register( oPackage )

oPackage:registerForm( 'FreeDownload' )

RETURN .T.

* -----------------

FUNCTION FreeDownload( oHtml, oContext )

LOCAL cName, cStreet1, cStreet2, cCompany, ;
      cEmail, cState, cZip, cPhone, cFax, cCountry, cCity

IF !DC_CGIInit(oHtml, oContext)
  RETURN .f.
ENDIF

dbeSetDefault('DBFCDX')

cName := DC_CGIGetParmVal('Name')
cCompany := DC_CGIGetParmVal('Company')
cStreet1 := DC_CGIGetParmVal('Street1')
cStreet2 := DC_CGIGetParmVal('Street2')
cState := DC_CGIGetParmVal('State')
cZip := DC_CGIGetParmVal('Zip')
cEmail := DC_CGIGetParmVal('Email')
cCountry := DC_CGIGetParmVal('Country')
cCity := DC_CGIGetParmVal('City')
cPhone := DC_CGIGetParmVal('Phone')
cFax := DC_CGIGetParmVal('Fax')

IF Empty(cName) .OR. !'@'$cEmail

  oHTML:message( "Error", ;
  'Please provide a Name and E-mail Address.<p>' + ;
  'Click on your Back Button to return to the download page.<p>')
  DC_CGIQuit()
  RETURN .t.

ELSE

  USE register INDEX register.cdx
  OrdSetFocus('EMAIL')
  SEEK Upper(Alltrim(cEmail))
  IF Eof() .AND. DC_AddRec(10)
    REPL REGISTER->name WITH cName,;
         REGISTER->company WITH cCompany,;
         REGISTER->street1 WITH cStreet1,;
         REGISTER->street2 WITH cStreet2,;
         REGISTER->city WITH cCity,;
         REGISTER->country WITH cCountry,;
         REGISTER->state WITH cState,;
         REGISTER->zip WITH cZip,;
         REGISTER->phone WITH cPhone,;
         REGISTER->fax WITH cFax,;
         REGISTER->email WITH cEmail,;
         REGISTER->filename WITH cVariable,;
         REGISTER->date WITH Date(),;
         REGISTER->time WITH Time()
     UNLOCK
   ENDIF

   RunShell('/C C:\spimail\sm.exe /t:' + Alltrim(cEmail) + ;
            ' /s:"File Download Instructions"' + ;
            ' /m:' + MemoRead('download.txt',,.t.,.t. )

   cHtml += 'An email message has been sent to <em><b>' + Alltrim(cEmail) + ;
            ' </b></em>with download instructions<br><br>'

  DC_CGINoCrSend(cHtml)

ENDIF

RETURN

Files:

_DCCGI.PRG, DCLIPX.DLL

See Also:

   dc_cgisend()


dc_cgiparamarray()

Return an array of all Data Variables

DC_CGIParmArray() returns a two-dimensional array with the case-sensitive name and the character string value of each variable passed to the CGI Program. This array is created by DC_CGIInit().

Syntax:

 DC_CGIParamArray( [<oHtml>] ) -> aVars

Returns:

 A two-dimensional array.  The first element contains the case
 sensitive variable name.  The second element contains the
 character string value.

Arguments:

<oHtml> is the HTML3 object passed to the program.  If this
parameter is not used then the HTML3 object posted by the
DC_CGIInit() function will be used.  CAUTION: When running
heavily loaded CGI programs that may receive simultaneous hits
it is recommended that this parameter be used.

Examples:

<form METHOD="POST" ACTION="/cgi-bin/waa1gate.exe?dummy=0">

     Your Name <input NAME="Name" TYPE="TEXT" size="20">
       Company <input NAME="Company" TYPE="TEXT" size="20">
       Street1 <input NAME="Street1" TYPE="TEXT" size="20">
       Street2 <input NAME="Street2" TYPE="TEXT" size="20">
          City <input NAME="City" TYPE="TEXT" size="20">
         State <input NAME="State" SIZE="10" TYPE="TEXT">
           Zip <input NAME="Zip" TYPE="TEXT" SIZE="10">
       Country <input NAME="Country" TYPE="TEXT" size="20">
E-Mail Address <input NAME="Email" TYPE="TEXT" size="20">
         Phone <input NAME="Phone" TYPE="TEXT" size="20">
           Fax <input NAME="Fax" TYPE="TEXT" size="20">

<input type=hidden name="WAA_PACKAGE" value="DS">
<input type=hidden name="WAA_FORM" value="FreeDownload">
<input type=SUBMIT name="FreeDownload" value="Download!"
</form>

FUNCTION _register( oPackage )

oPackage:registerForm( 'FreeDownload' )

RETURN .T.

* -----------------

FUNCTION FreeDownload( oHtml, oContext )

LOCAL cName, cStreet1, cStreet2, cCompany, ;
      cEmail, cState, cZip, cPhone, cFax, cCountry, cCity

IF !DC_CGIInit(oHtml, oContext)
  RETURN .f.
ENDIF

aVars := DC_CGIParamArray()
DC_ASave(aVars,'VARS.TXT')

RETURN nil

Files:

_DCCGI.PRG, DCLIPX.DLL

See Also:

   dc_cgiinit()


dc_cgisend()

Send data to the web browser

DC_CGISend() is used to send HTML data to the web browser.

Syntax:

 DC_CGISend( <cHTML>, [<oHtml>] ) -> nil

Returns:

 Nil.

Arguments:

<cHTML> is any HTML response.  The text will be added to any
previous calls to DC_CGISend() in the program and all text
will be sent when the program terminates.

<oHtml> is the HTML3 object passed to the program.  If this
parameter is not used then the HTML3 object posted by the
DC_CGIInit() function will be used.  CAUTION: When running
heavily loaded CGI programs that may receive simultaneous hits
it is recommended that this parameter be used.

Notes:

This must be the first DC_CGI*() function called in a WAA program.

Examples:

<form METHOD="POST" ACTION="/cgi-bin/waa1gate.exe?dummy=0">

     Your Name <input NAME="Name" TYPE="TEXT" size="20">
       Company <input NAME="Company" TYPE="TEXT" size="20">
       Street1 <input NAME="Street1" TYPE="TEXT" size="20">
       Street2 <input NAME="Street2" TYPE="TEXT" size="20">
          City <input NAME="City" TYPE="TEXT" size="20">
         State <input NAME="State" SIZE="10" TYPE="TEXT">
           Zip <input NAME="Zip" TYPE="TEXT" SIZE="10">
       Country <input NAME="Country" TYPE="TEXT" size="20">
E-Mail Address <input NAME="Email" TYPE="TEXT" size="20">
         Phone <input NAME="Phone" TYPE="TEXT" size="20">
           Fax <input NAME="Fax" TYPE="TEXT" size="20">

<input type=hidden name="WAA_PACKAGE" value="DS">
<input type=hidden name="WAA_FORM" value="FreeDownload">
<input type=SUBMIT name="FreeDownload" value="Download!"
</form>

FUNCTION _register( oPackage )

oPackage:registerForm( 'FreeDownload' )

RETURN .T.

* -----------------

FUNCTION FreeDownload( oHtml, oContext )

LOCAL cName, cStreet1, cStreet2, cCompany, ;
      cEmail, cState, cZip, cPhone, cFax, cCountry, cCity

IF !DC_CGIInit(oHtml, oContext)
  RETURN .f.
ENDIF

dbeSetDefault('DBFCDX')

cName := DC_CGIGetParmVal('Name')
cCompany := DC_CGIGetParmVal('Company')
cStreet1 := DC_CGIGetParmVal('Street1')
cStreet2 := DC_CGIGetParmVal('Street2')
cState := DC_CGIGetParmVal('State')
cZip := DC_CGIGetParmVal('Zip')
cEmail := DC_CGIGetParmVal('Email')
cCountry := DC_CGIGetParmVal('Country')
cCity := DC_CGIGetParmVal('City')
cPhone := DC_CGIGetParmVal('Phone')
cFax := DC_CGIGetParmVal('Fax')

IF Empty(cName) .OR. !'@'$cEmail

  oHTML:message( "Error", ;
  'Please provide a Name and E-mail Address.<p>' + ;
  'Click on your Back Button to return to the download page.<p>')
  DC_CGIQuit()
  RETURN .t.

ELSE

  USE register INDEX register.cdx
  OrdSetFocus('EMAIL')
  SEEK Upper(Alltrim(cEmail))
  IF Eof() .AND. DC_AddRec(10)
    REPL REGISTER->name WITH cName,;
         REGISTER->company WITH cCompany,;
         REGISTER->street1 WITH cStreet1,;
         REGISTER->street2 WITH cStreet2,;
         REGISTER->city WITH cCity,;
         REGISTER->country WITH cCountry,;
         REGISTER->state WITH cState,;
         REGISTER->zip WITH cZip,;
         REGISTER->phone WITH cPhone,;
         REGISTER->fax WITH cFax,;
         REGISTER->email WITH cEmail,;
         REGISTER->filename WITH cVariable,;
         REGISTER->date WITH Date(),;
         REGISTER->time WITH Time()
     UNLOCK
   ENDIF

   RunShell('/C C:\spimail\sm.exe /t:' + Alltrim(cEmail) + ;
            ' /s:"File Download Instructions"' + ;
            ' /m:' + MemoRead('download.txt',,.t.,.t. )

   cHtml += 'An email message has been sent to <em><b>' + Alltrim(cEmail) + ;
            ' </b></em>with download instructions<br><br>'

  DC_CGISend(cHtml)

ENDIF

RETURN

Files:

_DCCGI.PRG, DCLIPX.DLL

See Also:

   dc_cgiinit()


dc_cgisetparmval()

Set a data variable in a CGI program

DC_CGISetParmVal() is used to set the value of a data variable to be later passed back to the browser as a hidden variable.

Syntax:

 DC_CGISetParmVal( <cVarName>, ;
                   <cValue>, ;
                   [<oHtml>] ) -> cValue

Returns:

 A character string.

Arguments:

<cVarName> is the case sensitive name of the variable holding
the value.

<cValue> is the value to set.

<oHtml> is the HTML3 object passed to the program.  If this
parameter is not used then the HTML3 object posted by the
DC_CGIInit() function will be used.  CAUTION: When running
heavily loaded CGI programs that may receive simultaneous hits
it is recommended that this parameter be used.

Notes:

DC_CGIInit() must be called before using this function.

Variables passed to a CGI program are always character strings.

Examples:

TEXT TO FILE wishedit.txt

<div align="center">
<center>
<table border="4" cellpadding="5" width="100%" colspan="1"
  BORDERCOLOR="#7D7D7D">
  <tr>
    <td bgcolor="#9C6995">
      <font color=#FFFFFF>
      Editing WISHLIST<br> <font size=+1>Record:</font>
       <font size=5>
       <bold>"DCCGI_Record"</font></bold>
      <FONT SIZE=+1> "DCCGI_TitleMsg"</FONT>
    </td>
  </tr>
  <tr>
    <td bgcolor="#008080">
      <input type=submit value="First" name="DbEditAction">
      <input type=submit value="Prev" name="DbEditAction">
      <input type=submit value="Next" name="DbEditAction">
      <input type=submit value="Last" name="DbEditAction">
      <input type=submit value="Abort" name="DbEditAction">
      <input type=submit value="Commit" name="DbEditAction">
      <input type=submit value="New" name="DbEditAction">
      <input type=submit value="Browse" name="DbEditAction">
    </td>
  </tr>
  <tr>
    <td valign="top" bgcolor="#FFFFCC">
      <table width=500>
        <tr>
          <td><b><em>Name of WishMaker:</b></em></td>
          <td><b><em>Date of Wish:</em></b></td>
          <td><b><em>Status:</em></b></td>
        </tr>
        <tr>
          <td><b><font color="#0000FF">"DCCGI_UserName"
            </font></b></td>
          <td><b>"dCGI_WishDate"</b></td>
          <td><b>"nCGI_WishStatus"</b></td>
        </tr>
        <tr>
          <td colspan=3><b><em>Short Description:</em></b></td>
        </tr>
        <tr>
          <td colspan=3><input type=text name="cCGI_Description"
             size=75 maxlength=75></td>
        </tr>
      </table>
      <b><em>Explanation of Wish:</em></b><br>
      <TEXTAREA name="mCGI_Memo" rows=7 cols=80></TEXTAREA>
      <br>
      <b><em>Donnay Software Reply:</em></b><br>
      <TEXTAREA name="mCGI_Reply" rows=7 cols=80></TEXTAREA>
    </td>
  </tr>
</table>
</center>
</div>

ENDTEXT

cForm := DC_CGIStuff( WishEditFieldMap( .t., .t. ), ;
                      MemoRead( 'wishedit.txt' )

DC_CGISetParmVal('HiddenData','this is some data')
DC_CGISend(cForm)

RETURN nil

* --------------------

FUNCTION WishEditFieldMap( lEditMode )

RETURN  { ;
    { 'DCCGI_UserName', ;
       IIF(Empty(WISHLIST->user_name), ;
       DC_CGIGetParmVal('DCCGI_UserName'),WISHLIST->user_name), ;
       0 }, ;
    { 'dCGI_WishDate', ;
       IIF(Eof(),Date(),WISHLIST->date), ;
       0 }, ;
    { 'cCGI_Description', ;
       WISHLIST->descrip, ;
       IIF(lEditMode,1,0) }, ;
    { 'nCGI_WishStatus', ;
       WISHLIST->status, ;
       0 }, ;
    { 'sCGI_Version', ;
       WISHLIST->version, ;
       7 }, ;
    { 'mCGI_Memo', ;
       IIF(lEditMode,WISHLIST->memo, ;
       Strtran(WISHLIST->memo,Chr(13),'<BR>')), ;
       IIF(lEditMode,6,0) }, ;
    { 'mCGI_Reply', ;
       IIF(lEditMode,WISHLIST->reply, ;
       Strtran(WISHLIST->reply,Chr(13),'<BR>')), ;
       IIF(lEditMode .AND. lMasterPassWord,6,0) }, ;
    { 'DCCGI_Record', ;
       IIF( Eof(),0, RecNo()), ;
       0 }, ;
    { 'DCCGI_TitleMsg', ;
       TitleMessage(), ;
       0 } }

Files:

_DCCGI.PRG, DCLIPX.DLL

See Also:

   dc_cgigetparmval()
   dc_cgiinit()


dc_cgistuff()

Stuff an HTML response template with data

DC_CGIStuff() is used to merge data with an HTML form. This function is handy when is it desired to read a "template" HTML form, insert data in the template and then send this to the web browser.<br><br>

Syntax:

 DC_CGIStuff( <aStuff>, ;
              <cForm>, ;
              [<cDelim>], ;
              [<lMacro>] ) -> lStatus

Returns:

 A logical .TRUE. if the processed was completed successfully.

Arguments:

<aStuff> is a multi-dimensional array consisting of 3 sub
elements per item to stuff:

Element  Type    Description
-------  ------  --------------------------------------------
  [1]      C     The name of the variable in the HTML form
  [2]    CNDLM   Value to stuff into the form
  [3]      N     The type of variable (See below table)

Type [3]  Description
--------  ---------------------------------------------------
   0      ANYTHING (value may be any value)
   1      TEXT     (value must be character string) DEFAULT
   2      RADIO    (value must be character string)
   3      TEXT     (value must be date)
   4      TEXT     (value must be numeric)
   5      CHECKBOX (value must be logical)
   6      TEXTAREA (value must be character string)
   7      OPTION   (value must be character string)

<cForm> is the HTML form template

<cDelim> is the delimeter that is used around variables in the
form.  The default is ".

<lMacro> if .TRUE. specifies that element 2 of the stuff array
is an expression which will return a value.  The default is
.FALSE.

Examples:

FUNCTION XTest

TEXT TO FILE wishedit.txt

<div align="center">
<center>
<table border="4" cellpadding="5" width="100%" colspan="1"
  BORDERCOLOR="#7D7D7D">
  <tr>
    <td bgcolor="#9C6995">
      <font color=#FFFFFF>
      Editing WISHLIST<br> <font size=+1>Record:</font>
       <font size=5>
       <bold>"DCCGI_Record"</font></bold>
      <FONT SIZE=+1> "DCCGI_TitleMsg"</FONT>
    </td>
  </tr>
  <tr>
    <td bgcolor="#008080">
      <input type=submit value="First" name="DbEditAction">
      <input type=submit value="Prev" name="DbEditAction">
      <input type=submit value="Next" name="DbEditAction">
      <input type=submit value="Last" name="DbEditAction">
      <input type=submit value="Abort" name="DbEditAction">
      <input type=submit value="Commit" name="DbEditAction">
      <input type=submit value="New" name="DbEditAction">
      <input type=submit value="Browse" name="DbEditAction">
    </td>
  </tr>
  <tr>
    <td valign="top" bgcolor="#FFFFCC">
      <table width=500>
        <tr>
          <td><b><em>Name of WishMaker:</b></em></td>
          <td><b><em>Date of Wish:</em></b></td>
          <td><b><em>Status:</em></b></td>
        </tr>
        <tr>
          <td><b><font color="#0000FF">"DCCGI_UserName"
            </font></b></td>
          <td><b>"dCGI_WishDate"</b></td>
          <td><b>"nCGI_WishStatus"</b></td>
        </tr>
        <tr>
          <td colspan=3><b><em>Short Description:</em></b></td>
        </tr>
        <tr>
          <td colspan=3><input type=text name="cCGI_Description"
             size=75 maxlength=75></td>
        </tr>
      </table>
      <b><em>Explanation of Wish:</em></b><br>
      <TEXTAREA name="mCGI_Memo" rows=7 cols=80></TEXTAREA>
      <br>
      <b><em>Donnay Software Reply:</em></b><br>
      <TEXTAREA name="mCGI_Reply" rows=7 cols=80></TEXTAREA>
    </td>
  </tr>
</table>
</center>
</div>

ENDTEXT

cForm := DC_CGIStuff( WishEditFieldMap( .t., .t. ), ;
                      MemoRead( 'wishedit.txt' )

RETURN cForm

* --------------------

FUNCTION WishEditFieldMap( lEditMode )

RETURN  { ;
    { 'DCCGI_UserName', ;
       IIF(Empty(WISHLIST->user_name), ;
       DC_CGIGetParmVal('DCCGI_UserName'),WISHLIST->user_name), ;
       0 }, ;
    { 'dCGI_WishDate', ;
       IIF(Eof(),Date(),WISHLIST->date), ;
       0 }, ;
    { 'cCGI_Description', ;
       WISHLIST->descrip, ;
       IIF(lEditMode,1,0) }, ;
    { 'nCGI_WishStatus', ;
       WISHLIST->status, ;
       0 }, ;
    { 'sCGI_Version', ;
       WISHLIST->version, ;
       7 }, ;
    { 'mCGI_Memo', ;
       IIF(lEditMode,WISHLIST->memo, ;
       Strtran(WISHLIST->memo,Chr(13),'<BR>')), ;
       IIF(lEditMode,6,0) }, ;
    { 'mCGI_Reply', ;
       IIF(lEditMode,WISHLIST->reply, ;
       Strtran(WISHLIST->reply,Chr(13),'<BR>')), ;
       IIF(lEditMode .AND. lMasterPassWord,6,0) }, ;
    { 'DCCGI_Record', ;
       IIF( Eof(),0, RecNo()), ;
       0 }, ;
    { 'DCCGI_TitleMsg', ;
       TitleMessage(), ;
       0 } }

Files:

_DCCGI.PRG, DCLIPX.DLL

See Also:

   dc_cgiupdate()


dc_cgitrans()

Write a transacation to log file

DC_CGITrans() is used to write a transaction record to a database log named DCCGI.DBF. The record will contain the date and time, the names and values of all passed data variables (in array format) and the names and values of all passed environment variables (in array format).<br><br> A call to DC_CGITrans() is recommended right after the call to DC_CGIInit() in a CGI program. This will insure that all information passed to the program is permanently captured in the event of an error in the program. It can also be used as a history log to monitor all activity by the program.

Syntax:

 DC_CGITrans() -> lStatus

Returns:

 A logical .TRUE. if the transaction record was written, .FALSE.
 otherwise.

Arguments:

 None.

Notes:

The function DC_CGIInit() must be called before using this function.

Examples:

<form METHOD="POST" ACTION="/cgi-bin/waa1gate.exe?dummy=0">

     Your Name <input NAME="Name" TYPE="TEXT" size="20">
       Company <input NAME="Company" TYPE="TEXT" size="20">
       Street1 <input NAME="Street1" TYPE="TEXT" size="20">
       Street2 <input NAME="Street2" TYPE="TEXT" size="20">
          City <input NAME="City" TYPE="TEXT" size="20">
         State <input NAME="State" SIZE="10" TYPE="TEXT">
           Zip <input NAME="Zip" TYPE="TEXT" SIZE="10">
       Country <input NAME="Country" TYPE="TEXT" size="20">
E-Mail Address <input NAME="Email" TYPE="TEXT" size="20">
         Phone <input NAME="Phone" TYPE="TEXT" size="20">
           Fax <input NAME="Fax" TYPE="TEXT" size="20">

<input type=hidden name="WAA_PACKAGE" value="DS">
<input type=hidden name="WAA_FORM" value="FreeDownload">
<input type=SUBMIT name="FreeDownload" value="Download!"
</form>

FUNCTION _register( oPackage )

oPackage:registerForm( 'FreeDownload' )

RETURN .T.

* -----------------

FUNCTION FreeDownload( oHtml, oContext )

LOCAL cName, cStreet1, cStreet2, cCompany, ;
      cEmail, cState, cZip, cPhone, cFax, cCountry, cCity

IF !DC_CGIInit(oHtml, oContext)
  RETURN .f.
ENDIF

DC_CGITrans()

dbeSetDefault('DBFCDX')

cName := DC_CGIGetParmVal('Name')
cCompany := DC_CGIGetParmVal('Company')
cStreet1 := DC_CGIGetParmVal('Street1')
cStreet2 := DC_CGIGetParmVal('Street2')
cState := DC_CGIGetParmVal('State')
cZip := DC_CGIGetParmVal('Zip')
cEmail := DC_CGIGetParmVal('Email')
cCountry := DC_CGIGetParmVal('Country')
cCity := DC_CGIGetParmVal('City')
cPhone := DC_CGIGetParmVal('Phone')
cFax := DC_CGIGetParmVal('Fax')

IF Empty(cName) .OR. !'@'$cEmail

  oHTML:message( "Error", ;
  'Please provide a Name and E-mail Address.<p>' + ;
  'Click on your Back Button to return to the download page.<p>')
  DC_CGIQuit()
  RETURN .t.

ELSE

  USE register INDEX register.cdx
  OrdSetFocus('EMAIL')
  SEEK Upper(Alltrim(cEmail))
  IF Eof() .AND. DC_AddRec(10)
    REPL REGISTER->name WITH cName,;
         REGISTER->company WITH cCompany,;
         REGISTER->street1 WITH cStreet1,;
         REGISTER->street2 WITH cStreet2,;
         REGISTER->city WITH cCity,;
         REGISTER->country WITH cCountry,;
         REGISTER->state WITH cState,;
         REGISTER->zip WITH cZip,;
         REGISTER->phone WITH cPhone,;
         REGISTER->fax WITH cFax,;
         REGISTER->email WITH cEmail,;
         REGISTER->filename WITH cVariable,;
         REGISTER->date WITH Date(),;
         REGISTER->time WITH Time()
     UNLOCK
   ENDIF

   RunShell('/C C:\spimail\sm.exe /t:' + Alltrim(cEmail) + ;
            ' /s:"File Download Instructions"' + ;
            ' /m:' + MemoRead('download.txt',,.t.,.t. )

   cHtml += 'An email message has been sent to <em><b>' + Alltrim(cEmail) + ;
            ' </b></em>with download instructions<br><br>'

  DC_CGISend(cHtml)

ENDIF

RETURN

Files:

_DCCGI.PRG, DCLIPX.DLL

See Also:

   dc_cgiinit()


dc_cgiupdate()

Update a database from an array of information

DC_CGIUpdate() can be used in both web and non-web programs however it was designed for CGI programs to simplify the process of writing passed in data to a database because data is always received as character strings but it often must be saved to a database in another format like a date, numeric, logical, or memo.<br><br>

Syntax:

 DC_CGIUpdate( <aStuff>, ;
               [<cAlias>] ) -> lStatus

Returns:

 A logical .TRUE. if the update was performed successfully.

Arguments:

<aStuff> is a multi-dimensional array consisting of 3 sub
elements per item to update:

Element  Type    Description
-------  ------  --------------------------------------------
  [1]    CNLMDB  A value, code block, macro expression, or
                 name of variable.
  [2]      C     Name of field to update (fully aliased)
  [3]      N     The type of update to perform (default is 0)
                 See below table

  Type [3]       Description
--------------   --------------------------------------------
      0          Direct replacement (no translation) DEFAULT
    1,2,6        Character string [1] must be name of variable
      3          Date             [1] must be name of variable
      4          Numeric          [1] must be name of variable
      5          Logical          [1] must be name of variable
      7          Reserved
      8          Macro substitution

<cAlias> is the Alias of the database to update.  If this
argument is not passed then the current alias is the default.

Examples:

<form METHOD="POST" ACTION="/cgi-bin/waa1gate.exe?dummy=0">

     Your Name <input NAME="Name" TYPE="TEXT" size="20">
       Company <input NAME="Company" TYPE="TEXT" size="20">
       Street1 <input NAME="Street1" TYPE="TEXT" size="20">
       Street2 <input NAME="Street2" TYPE="TEXT" size="20">
          City <input NAME="City" TYPE="TEXT" size="20">
         State <input NAME="State" SIZE="10" TYPE="TEXT">
           Zip <input NAME="Zip" TYPE="TEXT" SIZE="10">
       Country <input NAME="Country" TYPE="TEXT" size="20">
E-Mail Address <input NAME="Email" TYPE="TEXT" size="20">
         Phone <input NAME="Phone" TYPE="TEXT" size="20">
           Fax <input NAME="Fax" TYPE="TEXT" size="20">

<input type=hidden name="WAA_PACKAGE" value="DS">
<input type=hidden name="WAA_FORM" value="FreeDownload">
<input type=SUBMIT name="FreeDownload" value="Download!"
</form>

FUNCTION _register( oPackage )

oPackage:registerForm( 'FreeDownload' )

RETURN .T.

* -----------------

FUNCTION FreeDownload( oHtml, oContext )

LOCAL cName, cStreet1, cStreet2, cCompany, ;
      cEmail, cState, cZip, cPhone, cFax, cCountry, cCity

IF !DC_CGIInit(oHtml, oContext)
  RETURN .f.
ENDIF

aUpdate := { ;
  { "Name",      "REGISTER->name",    1 }, ;
    "Company",   "REGISTER->company", 1 }, ;
    "Street1",   "REGISTER->street2", 1 }, ;
    "Street2",   "REGISTER->street2", 1 }, ;
    "City",      "REGISTER->city",    1 }, ;
    "State",     "REGISTER->state",   1 }, ;
    "Zip",       "REGISTER->zip",     1 }, ;
    "Country",   "REGISTER->country", 1 }, ;
    "Email",     "REGISTER->email,    1 }, ;
    "Phone",     "REGISTER->phone,    1 }, ;
    "Fax",       "REGISTER->fax,      1 }, ;
    "Date()",    "REGISTER->date,     8 }, ;
    {||Time()},  "REGISTER->time,     0 } }

USE REGISTER

DC_CGIUpdate( aUpdate, "REGISTER" )

RETURN nil

Files:

_DCCGI.PRG, DCLIPX.DLL


dc_chdir()

Change dos directory

DC_CHDIR() is used to select a new dos drive and directory.

Syntax:

DC_ChDir ( <cDirectory> ) -> lStatus

Returns:

 .TRUE. if the drive and/or directory exists and is selected.
 .FALSE. if the drive and/or directory does not exist.

Arguments:

<cDirectory> is the drive and directory to select.

Examples:

 DC_CHDIR('A:')
 DC_CHDIR('C:\DCLIP')
 DC_CHDIR('\DCLIP\DATA')

Files:

_DCCHDIR.PRG/.OBJ, DCLIPX.LIB


dc_childcount()

Report the number of child work areas

DC_CHILDCOUNT() is used to report the total number of parent-child relations for a specified work area.<br><br>

Syntax:

 DC_ChildCount ( [<nArea>] ) -> nChildren

Arguments:

<nArea> is the work area.  If argument is not passed, then the
current work area is default.

Examples:

 . use customer
 . use invoice new
 . use sales new
 . sele customer
 . set rela to cust_nmbr into invoice, to so_nmbr into sales
 . ? DC_CHILDCOUNT()
 2

Files:

_DCAREA.PRG, DCLIP1.DLL

See Also:

   dc_setrelation()


dc_chrsel()

Choose a character from an ASCII Character Chart

DC_ChrSel() will display a chart of the 256 ASCII text-mode characters and return the numeric value of the selected character.

Syntax:

 CHR

Returns:

 The numeric value of the character selected.

Arguments:

 None.

Notes:

CAUTION: This is a text-mode function so the SetAppWindow() must be a CRT window.

Examples:

 . ? dc_chrsel()

Files:

_DCCHR.PRG, DCLIP1.DLL

See Also:

   CHR


dc_clearevents()

Clear all events out of the Event Queue

DC_CLEAREVENTS() will clear all pending events from the event Queue. This is handy when calling a dialog function to insure that no mouse or keyboard events are in the queue thus adversely affecting the operation of the dialog window.

Syntax:

 DC_ClearEvents() -> nil

Returns:

 nil

Files:

_DCFUNCT.PRG/.OBJ, DCLIPX.DLL

See Also:

   dc_completeevents()
   dc_saveevents()
   dc_restoreevents()


dc_closearea()

Close the database that is open in the current work area

DC_CLOSEAREA() is a front-end to the Xbase++ function dbCloseArea(). Before calling dbCloseArea(), DC_CLOSEaREA() tests the function DC_UseDBFProtect(). If this function returns a logical .TRUE. then DC_CLOSEAREA() first modifies the header of the database before the database is closed to prevent other utility programs from being able to open the database. If a file header is modified by DC_CLOSEAREA(), then it can only be restored again by DC_USEAREA().<br><br>

Syntax:

 DC_CloseArea() -> nil

Returns:

 Nil.

Arguments:

 None.

Examples:

 . DC_UseDBFProtect(.t.)

 // open TEST.DBF
 . DC_UseArea( .t., 'DBFNTX', 'TEST' )

 // close TEST.DBF but first modify header to protect the data
 . DC_CloseArea()

Files:

_DCUSE.PRG, DCLIP2.DLL

See Also:

   dc_usedbfprotect()
   dc_usearea()


dc_clrarr()

Initialize or modify the Color Array

DC_CLRARR() is used to initalize or the dCLIP system color array. The color array is a PUBLIC array named DCCOLOR and is automatically initialized by any dCLIP function that uses the array. This function is normally not needed unless you are using the dCLIP color system in your own functions.<br><br> The first time the color array is initialized in an application using dCLIP functions, if a file named DCCOLOR.AR is found in the SET DCLIP directory, then the contents of the file will be used to intialize the array, otherwise the default colors will be used.<br><br> dCLIP also provides multiple "palettes" of colors which can be saved to DCCOLOR.AR and modified or selected via DC_CLRSETUP().

Syntax:

DC_ClrArr ( ) -> lStatus

Arguments:

 NONE

Notes:

dCLIP Color Manifest Constants from DCCOLOR.CH

Manifest constant Element Description ------------ ----------------------- ---------------------------- cC_DOTPROMPT dCCOLOR[dCCOLOR[1]+1,1] Main dot-prompt cC_BRMENUF dCCOLOR[dCCOLOR[1]+1,2] Browse menus frame cC_BRMENUD dCCOLOR[dCCOLOR[1]+1,3] Browse menus data cC_BRMENUH dCCOLOR[dCCOLOR[1]+1,4] Browse menus header cC_BRMENUB dCCOLOR[dCCOLOR[1]+1,5] Browse menus menu bar cC_BRMENUS dCCOLOR[dCCOLOR[1]+1,6] Browse menus select bar cC_POPMENF dCCOLOR[dCCOLOR[1]+1,7] Popup / pulldown menu frames cC_POPMENI dCCOLOR[dCCOLOR[1]+1,8] Popup / pulldown menu items cC_POPMENS dCCOLOR[dCCOLOR[1]+1,9] Popup / pulldown menu select bars cC_MEMOBOX dCCOLOR[dCCOLOR[1]+1,10] All memos box cC_MEMOTXT dCCOLOR[dCCOLOR[1]+1,11] All memos contents cC_EXPBOXF dCCOLOR[dCCOLOR[1]+1,12] Exploding boxes frame cC_EXPBOXC dCCOLOR[dCCOLOR[1]+1,13] Exploding boxes contents cC_DBUGGER dCCOLOR[dCCOLOR[1]+1,14] DBUGGER main screen cC_WARNBOX dCCOLOR[dCCOLOR[1]+1,15] Warning boxes frame cC_WARNTXT dCCOLOR[dCCOLOR[1]+1,16] Warning boxes contents cC_DBUGBOX dCCOLOR[dCCOLOR[1]+1,17] Debug boxes frames cC_DBUGTXT dCCOLOR[dCCOLOR[1]+1,18] Debug boxes contents cC_DBUGBAR dCCOLOR[dCCOLOR[1]+1,19] Debug boxes select bar cC_SPECIAL dCCOLOR[dCCOLOR[1]+1,20] Special codes cC_SAY dCCOLOR[dCCOLOR[1]+1,21] SAYs cC_PENDGET dCCOLOR[dCCOLOR[1]+1,22] Pending GETs cC_CURRGET dCCOLOR[dCCOLOR[1]+1,23] Current GET cC_STAT1 dCCOLOR[dCCOLOR[1]+1,24] Dot-prompt status line / lines cC_STAT2 dCCOLOR[dCCOLOR[1]+1,25] Dot-prompt status line / data lC_BLINKBIT dCCOLOR[dCCOLOR[1]+1,34] Blink-bit or High Intensity cC_SETNAME dCCOLOR[dCCOLOR[1]+1,35] Name of this color set cC_COLORNAME 35 Numeric value of cC_SETNAME nC_COLORPAL dCCOLOR[1] Default color palette

Examples:

 #include "dccolor.ch"

 FUNCTION main

 DC_CLRARR()           // initalize array
 dc_expl(10,10,15,70)  // explode a box
 setcolor(cC_EXPBOXC)  // set color to box contents
 @ 12,12 say 'Enter something below'
 something := space(10)
 @ 14,12 get something
 read

Files:

_DCCOLOR.PRG/.OBJ, DCLIPX.LIB

See Also:


dc_clrscope()

Clear scoping values for the current work area

DC_CLRSCOPE() is used to clear both the SCOPE TOP and SCOPE BOTTOM "scoping range" values that were previously set by DC_SETSCOPE().<br><br>

Syntax:

dc_clrscope ( ) -> Nil

Returns:

 Nil

Arguments:

 None.

Notes:

DC_SETSCOPE() does not establish the scoping range at the RDD-layer level, but instead is just a handy way of storing the SCOPE TOP and SCOPE BOTTOM to be retrieved by programs that can use this information such as data-entry systems and browse systems. It does not affect the behavior of the data-driver nor does it set any filters on the data.

Examples:

 #include 'dcdialog.ch'
 #include 'appevent.ch'

 PROCEDURE XTest()

 LOCAL GetList := {}, oBrowse, aPres, cScopeTop, cScopeBot

 USE ..\XDOC\EXPRESS INDEX ..\XDOC\EXPRESS.CDX ;
     VIA FOXCDX ALIAS XDOC

 OrdSetFocus('COMMAND')
 DC_KeyStat(.t.)
 DC_SETSCOPE(0,'DC_G')
 DC_SETSCOPE(1,'DC_K')
 DC_DbGoTop()

 aPres := ;
  { { XBP_PP_COL_HA_FGCLR, GRA_CLR_WHITE },    /*  Header FG Color  */ ;
    { XBP_PP_COL_HA_BGCLR, GRA_CLR_DARKGRAY }, /*  Header BG Color  */ ;
    { XBP_PP_COL_DA_ROWSEPARATOR, XBPCOL_SEP_DOTTED }, /* Row Sep  */  ;
    { XBP_PP_COL_DA_COLSEPARATOR, XBPCOL_SEP_DOTTED }  /* Col Sep  */  ;
  }

 cScopeTop := Pad('DC_G',10)
 cScopeBot := Pad('DC_K',10)

 @ 1,1 DCSAY 'Scope Top' GET cScopeTop PICT '@!' SAYRIGHT ;
   VALID {||DC_SetScope(0,Alltrim(cScopeTop)),;
            oBrowse:RefreshAll(),;
            SetAppFocus(oBrowse),.t.}

 @ 1,25 DCSAY 'Scope Bottom' GET cScopeBot PICT '@!'  SAYRIGHT ;
   VALID {||DC_SetScope(1,Alltrim(cScopeBot)),;
            oBrowse:RefreshAll(),;
            SetAppFocus(oBrowse),.t.}

 @ 1, 65 DCPUSHBUTTON CAPTION 'Clear ~Scope' SIZE 10,1.5 ;
   ACCELKEY xbeK_ALT_S ;
   ACTION {||DC_CLRSCOPE(),oBrowse:RefreshAll(),;
             SetAppFocus(oBrowse)}

 @ 3,1 DCBROWSE oBrowse ALIAS 'XDOC' ;
   SIZE 77,11.8 ;
   FREEZELEFT {1} ;
   PRESENTATION aPres ;
   SCOPE

 DCBROWSECOL FIELD XDOC->command ;
   HEADER "Command" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->type  ;
   HEADER "Type" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->short ;
   HEADER "Short Description" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->module ;
   HEADER "Module" PARENT oBrowse ;

 DCBROWSECOL FIELD XDOC->category ;
   HEADER "Category" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->see_also ;
   HEADER "See Also" PARENT oBrowse

 DCREAD GUI ;
   FIT ;
   ADDBUTTONS ;
   TITLE 'Scoping Demo: DC_G thru DC_K'

 RETURN

Files:

_DCSCOPE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_setscope()


dc_cls()

Perform a clear screen of a window created by DC_EXPL()

DC_CLS() is a Dual-Mode function which is used to clear all the text in a TEXT window or GUI dialogue that was created by DC_EXPL(). <br><br>

Syntax:

DC_Cls ( [<aSaveScreen>] ) -> nil

Returns:

 NIL

Arguments:

<aSaveScreen> is an array of screen information that was
originally returned by DC_EXPL().  If no parameter is
passed, then the static array posted by the last usage of
DC_EXPL() or the DCEXPLODE command will be used for the
screen information.  If no call to DC_EXPL() or DCEXPLODE
is made since the last call to DC_IMPL() or DCIMPLODE,
then the text is written to the CRT window and treated as
a normal @..SAY.

Examples:

 aText := { "Enter a name to search.",;
           "The name must start with",;
           "an alphabet character" }
 disp_msg( 10,10,15,40,aText )
 return

 /* --------- */

 FUNC disp_msg ( nSrow, nScol, nErow, nEcol, aText )

 DC_Gui(.t.)  // display a gui dialogue
 cScreen := dc_expl( nSrow, nScol, nErow, nEcol )
 for i := 1 to len(aText)
   DC_SAY( i+1, 2, aText[i] )
 next

Files:

_DCEXPL.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_expl()


dc_cmonth()

Translated name of the Month

DC_Cmonth() is used to get the name of the month for a specified date. The name is translated to the language previously selected by DC_LangSel().

Syntax:

DC_CMonth( <dDate> ) -> cMonth

Returns:

A character string.

Arguments:

<dDate> is any valid date type.

Examples:

DC_LangSet( DCLANG_GERMAN )
? DC_CMonth( Date() )
Oktober

Files:

_DCCALEN.PRG, DCLIPX.DLL

See Also:

   dc_cdow()
   dc_langset()
   dc_langmsg()


dc_codedelete()

Delete a code table

DC_CODEDELETE() is used to delete a code table from the code table file.<br><br>

Syntax:

dc_codedelete ( [<cTableName>] ) -> lStatus

Arguments:

<cTableName> is the name of the code table.  This is a name of
up to eight (8) digits.  If no argument is passed, then a pick
list of all code tables in the code table file will be displayed.

Notes:

The DCCODES.DBF file and its indexes will be created by the DC_CodeOpen() function if it they do not already exist.

Examples:

 DC_CODEELETE('POSITION')

Files:

_DCCODES.PRG, DCLIP1.DLL

See Also:

   dc_codeedit()
   dc_codeget()
   dc_codeload()


dc_codeedit()

Edit a Code Table

DC_CodeEdit() is an editor that is used to maintain the DCCODES.DBF dictionary file. Code Tables are groups of records that are loaded into an array pick-list and used in validations when using the eXPress++ data-driven Browse and Edit (data-entry) system. When a "T" validation is used in a field-array, this pops-up a code table pick-list for the operator to choose possible values. Code tables can also be used in custom applications where validations and/or choice boxes are required.<br><br> For example a code table named "POSITION" can be added to provide a picklist of available entries for a field of baseball player positions. They would be entered in a code table as follows:<br><br> 1B - First Base 2B - Second Base 3B - Third Base P - Pitcher SS - Short Stop RF - Right Field LF - Left Field CF - Center Field C - Catcher<br><br> A choice from this table can then be selected by calling DC_CodeGet() in a validation or popup routine.<br><br>

Syntax:

dc_codeedit ( [ <cCodeTable> | <aCodeTable> ] ) -> aCodeTable

Returns:

 A 2-dimensional array of two sub-arrays.

 The first array contains general information about the
 screen group.

  Element  Type   Description
  -------  ----  --------------------------------------
    [1]     C    Code Table Name (up to 8 characters)
    [2]     C    Code Table Description

 The second array contains one sub-array for each code
 table item.

  Element  Type   Description
  -------  ----  ---------------------------------------
    [1]     C    Code Table Name (up to 8 chars)
    [2]     C    Code Name (up to 10 chars)
    [3]     C    Code Description (up to 50 chars)
    [4]     C    Code Sequence (used for indexing file)
    [5]     C    Code UR (reserved)

Arguments:

<cCodeTable> is the name of the code table in DCCODES.DBF
to load and edit (up to 8 characters) or <aCodeTable> is a
Code Table array.  See RETURNS for a specification of this
array.  If no parameter is passed, a pick-list of all Code
Tables in DCCODES.DBF will be displayed.

Notes:

The DCCODES.DBF file and its indexes will be created by the DC_CodeOpen() function if it they do not already exist.

Examples:

 -- Example 1 --
 // Load a code table from the dictionary and edit it //
 DC_CODEDIT()

 -- Example 2 --
 // Edit code table "POSITION"
 DC_CODEEDIT("POSITION")

 -- Example 3 --
 // Edit a code table array and save it to dictionary //
 aCodeTable := DC_CodePick()
 aCodeTable := DC_CODEDIT( aCodeTable )
 DC_CodeSave( aCodeTable )

Files:

_DCCODES.PRG, DCLIP1.DLL

See Also:

   CODE EDIT


dc_codeget()

Get a choice from a code table

DC_CODEGET() is used to allow the operator to select a code from a designated code table. All codes are stored in the DCCODES.DBF database in separate tables.<br><br> "User defined fields" allow data to easily be extracted from a code table via the DC_CODEGET() function.<br><br> The "definition" of the three fields is established under the "options" for the code table. Each of the fields is a character type field with a length of 50. For example, let's establish a code table named "REPORTS" with the following data:<br><br> Code Description User Field 1 User Field 2<br><br> ---- ------------------ ---------------- ----------------- R001 Inventory Report INVREPT.EXE Executable Program R002 Sales Report {||SlsRept()} Code-Block R003 End-of-Month EOF.RP1 R&R Report<br><br> Now, you can use DC_CODEGET() to place "virtual" fields on the screen so you can display the Description, User Field 1 and User Field 2 based on the code entered into another field.

Syntax:

DC_CodeGet ( <cTableName>, ;
             [@<cCode>], ;
             [<cTitle>], ;
             [<lForcePick>], ;
             [@<cDesc>], ;
             [@<aCode>], ;
             [<lNoPick>], ;
             [<lCurrPos>], ;
             [<lValidate>] ) -> cCode

Returns:

 The value of the code chosen (a Character string) if <lValidate>
 is .FALSE.

 IF <lValidate> is .TRUE. then the returned value is a logical
 .TRUE. if the user selected a code from the table, otherwise a
 logical .FALSE. is returned.  Also, the selected value is returned
 in the variable @<cCode> when it is passed by reference.

Arguments:

<cTableName> is the name of the code table in DCCODES.DBF.
to load (up to 8 characters).

@<cCode> is an optional value to seek in the code table. If
the value is found and <lPickList> is .FALSE. then the
full value will be returned and the description will be
placed into the @<cDesc> variable.  If the value is not
found or <lForcePick> is .TRUE., a pick list will be
displayed for the user to choose a code.

<cTitle> is the title to place at the top of the picklist.
If no parameter is passed, then a default title is displayed.

@<cDesc> is a variable to be passed by reference.  The value
in the description field (CODE_DESC) will be placed into
this variable.

@<aCode> is a variable to be passed by reference.  The value
of all database fields for the selected code will be placed
into an array of 6 elements and placed into this variable.

  Element       Field Name
  -------       ------------
     1          CODE_NAME
     2          CODE_DESC
     3          CODE_SEQ
     4          CODE_UR
     5          CODE_UDF1
     6          CODE_UDF2

<lNoPick> if .TRUE. will not display a pick-list if the code
cannot be found.

<lCurrPos> if .TRUE. (default) will display the window at the
current mouse position.

<lValidate> if .TRUE. will return a logical value rather than
the selected code table value.  See RETURNS.

Notes:

The DCCODES.DBF file and its indexes will be created by the DC_CodeOpen() function if it they do not already exist.

Examples:

--- Example 1 ---

 LOCAL GetList := {}, cTreatment

 cTreatment := Space(10)
 @ 12,12 DCSAY "Enter Treatment Plan Code" GET cTreatment ;
   PICT '@!' POPUP {|c|DC_CODEGET('TRTMENT',c,,.t.)} )

 DCREAD GUI FIT ADDBUTTONS MODAL TITLE 'Treatment'

 RETURN cTreatMent

 --- Example 2 ---

 To display the description:
  Eval({|a|DC_CodeGet('REPORTS',repttype,,,,@a,.t.),a[2]})

 To display user field 1:
  Eval({|a|DCC_odeGet('REPORTS',repttype,,,,@a,.t.),a[3]})

 To display user field 2:
  Eval({|a|DC_CodeGet('REPORTS',repttype,,,,@a,.t.),a[4]})

Files:

_DCCODES.PRG, DCLIP1.DLL

See Also:

   dc_codeedit()
   dc_codeload()


dc_codeimp()

Import a code table

DC_CODEIMP() is used to import a code table from the DXCODES.DBF import/export file to the DCCODES.DBF file.<br><br>

Syntax:

dc_codeimp ( [<cTableName> | "ALL"] ) -> lStatus

Returns:

 A logical .TRUE. if the files were imported successfully.

Arguments:

<cTableName> is the name of the code table.  This is a name of
up to eight (8) digits.  If a code table name is passed then
the DXCODES.DBF database will be searched and all code table
items that match the code table name will be imported into
DCCODES.DBF.  If no name is passed, then a pick-list of all tables
stored in the DXCODES.DBF database will be displayed.

If "ALL" is passed as the table name, then all tables in the
DXCODES.DBF will be imported into DCCODES.DBF.

Notes:

The DCCODES.DBF file is the data-dictionary database that contains all code tables. If this file does not exist in your default directory or path then it will be created. The DXCODES.DBF file is the data-dictionary database that contains all code tables that were exported from another system.

Examples:

 DC_CODEIMP( "ALL" )

Files:

_DCCODES.PRG, DCLIP1.DLL

See Also:

   dc_codeedit()
   dc_codeget()
   dc_codeload()


dc_codeload()

Load a code table into an array

DC_CODELOAD() is used to load a code table array from the DCCODES.DBF dictionary file.

Syntax:

dc_codeload ( [<cCodeTable>], ;
              [<lCache>], ;
              [<lExport>] ) -> aCodeTable

Returns:

 A 2-dimensional array of two sub-arrays.

 The first array contains general information about the
 screen group.

  Element  Type   Description
  -------  ----  --------------------------------------
    [1]     C    Code Table Name (up to 8 characters)
    [2]     C    Code Table Description

 The second array contains one sub-array for each code
 table item.

  Element  Type   Description
  -------  ----  ---------------------------------------
    [1]     C    Code Table Name (up to 8 chars)
    [2]     C    Code Name (up to 10 chars)
    [3]     C    Code Description (up to 50 chars)
    [4]     C    Code Sequence (used for indexing file)
    [5]     C    Code UR (reserved)

Arguments:

<cCodeTable> is the name of the code table in DCCODES.DBF
to load (up to 8 characters).  If no parameter is passed, a
pick-list of all Code Tables in the DCCODES.DBF dictionary
will be displayed.

<lCache> if .TRUE. (default) will save the table to a static
cache array so the next time it is requested it will be
 reloaded from the static array for faster speed.  If .FALSE.
then it will not be saved to the cache.

<lExport> if .TRUE. will open the DXCODES.DBF (import/export)
file rather than the DCCODES.DBF file.

Notes:

The DCCODES.DBF file and its indexes will be created by the DC_CodeOpen() function if it they do not already exist.

Examples:

 . aCodeTable := DC_CODELOAD( 'POSITION' )
 . aCodeTable := DC_CodeEdit( aCodeTable )
 . DC_CodeSave( aCodeTable )

Files:

_DCCODES.PRG, DCLIP1.DLL

See Also:

   dc_codeedit()
   dc_codeget()


dc_codepick()

Pick a code table from the Code Table File

DC_CODEPICK() is used to pick the name of a code table from the DCCODES.DBF Code Table dictionary.<br><br>

Syntax:

dc_codepick ( [<cTitle>], ;
              [<lExport>], ;
              [@<cTableDesc>], ;
              [<aCodeList>], ;
              [<lNoPick>] ) -> cTableName

Returns:

 A character string containing the name of the code table
 selected by the user.

Arguments:

<cTitle> is the title to display on the pick-list box.

<lExport> if .TRUE. will open the DXCODES.DBF (import/export)
file rather than the DCCODES.DBF file.

@<cTableDesc> is the name of a variable (passed by reference)
to store the description of the table that was chosen.

@<aCodeList> is the name of a variable (passed by reference)
to store a single-dimensional array containing the names of
all code tables in the code table file.

<lNoPick> if .TRUE. will not pop up the list of code tables
to choose.  This option is intended to be used only when
@<aCodeList> is also passed.

Notes:

The DCCODES.DBF file and its indexes will be created by the DC_CodeOpen() function if it they do not already exist.

Examples:

 cCodeTable := DC_CODEPICK()
 IF !Empty(cCodeTable)
   aCodeTable := DC_CodeEdit( cCodeTable )
 ENDIF

Files:

_DCCODES.PRG, DCLIP1.DLL

See Also:

   dc_codeedit()
   dc_codeget()


dc_coderename()

Rename a Code Table

DC_CodeRename() is used to rename a Code Table.

Syntax:

DC_CodeRename( [<cTableName>], ;
               [<cNewName>], ;
               [<cNewDesc>] ) -> lStatus

Returns:

 A logical .TRUE. if the rename was successful.

Arguments:

<cTableName> is the name of the table to rename.  This is a
name of up to 10 characters.  If no name is given, then a pick
list of all code tables will be displayed.

<cNewName> is the new name.  If no name is given, then a
dialog window will be displayed to enter a new name.

<cNewDesc> is the new description.  If no description is given,
the old description will be used.

Examples:

 DC_CodeRename( 'BULLET', 'BULLETS' )

Files:

_DCCODES.PRG, DCLIP1.DLL

See Also:

   CODE RENAME
   dc_codeedit()


dc_codesave()

Save a code table array to the Code Table file

DC_CODESAVE() is used to save a code table array to the DCCODES.DBF dictionary file.<br><br>

Syntax:

dc_codesave ( <aCodeTable>, ;
              [<lExport>] ) -> lStatus

Returns:

 A logical .TRUE. if the code table was saved, .FALSE. otherwise.

Arguments:

<aCodeTable> is a code table array that conforms to the
specification of the array documented in RETURNS for the
function DC_CODEEDIT().

<lExport> if .TRUE. will save to the DXCODES.DBF (import/export)
file rather than DCCODES.DBF.

Notes:

The DCCODES.DBF file and its indexes will be created by the DC_CodeOpen() function if it they do not already exist.

Examples:

 aCodeTable := DC_CodePick()
 aCodeTable := DC_CodeEdit( aCodeTable )
 DC_CODESAVE( aCodeTable )

Files:

_DCCODES.PRG, DCLIP1.DLL

See Also:

   dc_codeedit()
   dc_codeget()
   dc_codeload()


dc_color()

Set the current screen color value

DC_COLOR() is a replacement for SETCOLOR(). DC_COLOR() automatically tests the status of ISCOLOR() and a STATIC variable named COLOR_MON to determine if the application is being run on a color monitor. This allows the programmer or user to enable all color output dynamically by simply turning color on or off with the DC_COLORSET() function.<br><br>

Syntax:

DC_Color ( <cColorString> | <nColorElement>,  ;
           [<lSelectBar>], ;
           [<lReverseVideo>] ) -> cColorString

Returns:

 A numeric value equal to the palette number of the new color palette.

Arguments:

<cColorString> is the color string value to set.  See the
color definitions in DCCOLOR.CH.  String definitions start
with cC_*.

  or

<nColorElement> is the number of the color based on the table
of Numeric color definitions in DCCOLOR.CH.  Numeric definitions
start with nC_*.

<lSelectBar> if .TRUE. will set the color to "highlight" if
application is being run on a monochrome monitor or COLOR_MON
is .FALSE.

<lReverseVideo> is used only if <lSelectBar> is .TRUE.  If
.TRUE., this argument will set highlight to "reverse video".

Examples:

 #include "dccolor.ch"

 // Set color to Browse menus frame color
 // Use numeric value - nC_BRMENUF is defined as 2
 // This is the preferred method for speed and code size
 // Use this method if you are using dCLIP colors
 DC_COLOR( nC_BRMENUF )

 // Set color to Browse menus frame color
 // Use Character string value
 // cC_BRMENUF is defined as DCCOLOR[DCCOLOR[1]+1,2]
 // This method is provided only for backward compatability
 DC_COLOR( cC_BRMENUF )

 // Set color to 'BG+/W'
 // Use Character string value
 DC_COLOR( 'BG+/W' )

Files:

_DCCOLOR.PRG/.OBJ, DCLIPX.LIB


dc_color2array()

Convert a color string to an array

DC_COLOR2ARRAY() is a handy function which is used to convert a standard "complex" Clipper color string to an array of individual colors.

Syntax:

DC_Color2Array( [<cColorString>] ) -> aColor

Returns:

 An array of 5 elements;

 Element  Type  Color
 -------  ----  -------------------------
   [1]     C    Standard (screen output)
   [2]     C    Enhanced (GETS, hilites)
   [3]     C    Border
   [4]     C    Background (unsupported)
   [5]     C    Unselected GETS

Arguments:

<cColorString> is a valid Clipper color string.  If no
parameter is passed, then the current SETCOLOR() will be
used.

Examples:

 PROCEDURE XTest()

 LOCAL cColorString := 'W+/B,,N/BG'

 DC_Gui(.t.)

 DC_MsgBox( DC_COLOR2ARRAY() )

 DC_MsgBox( DC_COLOR2ARRAY( cColorString ) )

 RETURN

Files:

_DCCOLOR.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_color()


dc_color2gra()

Convert a color string to a GUI compatible color

DC_COLOR2GRA() is used to convert a Text-Based color string to a 2 element array containing a foreground and background color which is compatible with GUI objects.

Syntax:

DC_Color2Gra( [<cColorString>] ) -> aColor

Returns:

 An array of 2 elements;

 Element  Type  Description
 -------  ----  -------------------------
   [1]     N    ForeGround Color
   [2]     N    BackGround Color

Arguments:

<cColorString> is a valid Clipper color string.  If no
parameter is passed, then the first color in the current
SETCOLOR() will be used.

Examples:

 #include 'dcdialog.ch'

 PROCEDURE XTest()

 LOCAL GetList := {}, cColor := 'GR+/R', aPres, aColor

 aColor := DC_Color2Gra(cColor)

 aPres := { {XBP_PP_FGCLR, aColor[1]},;
            {XBP_PP_BGCLR, aColor[2]} }

 @ 0,0 DCSAY 'This should be yellow on red' SAYSIZE 40,2 ;
   FONT 'Helv.32' COLOR aColor[1], aColor[2]

 DCREAD GUI ;
   FIT ;
   ADDBUTTONS

 RETURN

Files:

_DCCOLOR.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_say()
   dc_gra2color()


dc_coloradd()

Add a new color set to the Color Array

DC_COLORADD() will add a new color palette set to the color array and save the contents to DCCOLOR.AR for restoring with the DC_CLRARR() initialize function.

Syntax:

DC_ColorAdd ( ) -> nPalette

Arguments:

 NONE

Files:

_DCCOLOR.PRG/.OBJ, DCLIPX.LIB


dc_colordel()

Delete a color set from the Color Array

DC_COLORDEL() is used to delete a color palette that was created with DC_COLORADD().

Syntax:

DC_ColorDel ( [<nPalette>] ) -> lStatus

Arguments:

<nPalette> is the number of the color palette to delete.  You
cannot delete color palette number 0 or 1, so this number must
be greater than 1.  If no argument is given, then a pick-list
of palette descriptors will be displayed.

Examples:

 . nPalette := dc_coloradd()
 . DC_COLORDEL( nPalette )

Files:

_DCCOLOR.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_coloradd()


dc_colorlist()

Convert a GRA_CLR_* numeric index to a description array

DC_COLORLIST() is used create an array of character strings that represent a conversion of standard GRA_CLR_* numeric values. This is a handy function which is used to create a picklist of colors by color name.

Syntax:

DC_ColorList( <nColor>,  ;
              [@<aColorTypes>], ;
              [@<aColors>] ) -> cColor

Returns:

 A Character String

Arguments:

<nColor> is an index from -5 to 15.

@<aColorTypes> is an optional memory variable to store a
single-dimensional array of 21 characters representing the
colors for index values from -5 to 15.

@<aColors> is an optional memory variable to store a
multi-dimensional array of 21 sub-elements representing the
colors for index values from -5 to 15.

Examples:

 #include 'gra.ch'

 PROCEDURE XTest()

 LOCAL nColor := GRA_CLR_GREEN, aColorList, aColors, cColor

 cColor := DC_ColorList( nColor, @aColorList, @aColors )

 DC_Gui(.t.)

 DC_MsgBox( { cColor, ;
              aColorList[GRA_CLR_DARKGRAY], ;
              aColors[GRA_CLR_YELLOW] } )

 DC_MsgBox( aColorList )

 RETURN

Files:

_DCCOLOR.PRG/.OBJ, DCLIPX.LIB


dc_colormode()

Enable or Disable Color / Monochrome display mode

DC_COLORMODE() is used to enable or disable the color display. Use this function to disable color mode when using dCLIP functions in an application that is running on a monochrome display with a color driver board that returns an ISCOLOR() of .true.

Syntax:

DC_ColorMode ( [<lColorOn>] ) -> lStatus

Arguments:

<lColorOn> if .TRUE. will enable the color display, if .FALSE.
will enable monochrome display.

Examples:

 . DC_COLORMODE(.f.)  // disable color display

Files:

_DCCOLOR.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_color()


dc_colorrest()

Restore a color set

DC_COLORREST() is used to restore a color palette that was previously saved with DC_COLORSAVE().<br><br>

Syntax:

DC_ColorRest( <nPalette> ) -> nil

Arguments:

<nPalette> is the number of the palette that was saved with the
DC_SAVECOLOR() function.

Examples:

 . nPalette := dc_colorsave()  // save color palette
 . do something
 . DC_COLORREST( nPalette )    // restore old color palette

Files:

_DCCOLOR.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_colorsave()


dc_colorsave()

Save the current color set

DC_COLORSAVE() is used to save the number of the currently selected color palette for later restoring with DC_COLORREST(). Use DC_COLORSAVE() and DC_COLORREST() if you are calling a function that might select a different color palette such as DC_BROWSEDB().

Syntax:

DC_ColorSave() -> nPalette

Arguments:

 NONE

Examples:

 . nPalette := DC_COLORSAVE()  // save selected palette number
 . do something
 . dc_colorrest( nPalette )    // restore old color palette

Files:

_DCCOLOR.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_colorrest()


dc_colorsel()

Select a color set from the Color Array

DC_COLORSEL() is used to select a color palette. The default number of palettes in the dCLIP color system is one (1), so this function is useful only after creating extra color palettes with the DC_COLORADD() function.<br><br> Multiple color palettes are provided in the dCLIP system for the following purpose:<br><br> 1. To allow the user to select a different color set when using dCLIP functions in applications that must be run on multiple display systems. For example, if you work with dCLIP part time on a color monitor and part time on an LCD display, you can create color palettes that are "optimized" for you display type.<br><br> 2. To allow the user to select different color sets for different windows in an application.

Syntax:

DC_ColorSel( [<nPalette>] ) -> nPalette

Arguments:

<nPalette> is the number of the color palette to select.  If no
argument is passed then the number of the currently selected
palette will be returned.  If a 0 is passed or if the number is
not a valid palette number then a pick-list of available palette
descriptions will be displayed.

Examples:

 . nPalette := dc_colorsave()
 . DC_COLORSEL(0)            // select a color palette
 . do something
 . dc_colorrest( nPalette )  // restore the old palette

Files:

_DCCLR2.PRG/.OBJ, DCLIPX.LIB

See Also:


dc_compile()

Compile a source .PRG or all changed .PRGs

DC_COMPILE() compiles a specified .PRG file into an .OBJ file or recompiles all .PRG files which have been modified and have a later date/time stamp than their associated .OBJ file.<br><br> Use DC_COMPILE() after editing your source files. DC_COMPILE() checks the date and time stamp on .PRG files and compares them to the date and time on any corresponding .OBJ files. If the date and/or time on a .PRG is later than the corresponding .OBJ, the .PRG will be compiled with the /m option.<br><br>

Syntax:

 DC_Compile ( [<cFileName>], ;
              [<cCompOpt>], ;
              [<lQuiet>], ;
              [<lWindow>], ;
              [<lReCompile>] ) -> lStatus

Arguments:

<cFileName> is the name of the file to compile.  If this
argument is left blank, then all .PRG files which have a later
date stamp than the associated .OBJ file will be compiled.

<cCompOpt> is a string of compiler options.  If no argument is
given, then the options established by DC_SETT('XPPOPT',<cOptions>),
SET XPPOPT TO <cOptions> or XPPOPT=<cOptions> (DCLIP.SYS) are
used as the default.

<lQuiet> if .TRUE. will prevent displaying the status after
compiling. If .FALSE. (default), then all errors will be
displayed.

<lWindow> if .TRUE. (default) will display a window showing the
compiled results.

<lReCompile> if .TRUE. will force a recompile of <cFileName>
regardless of the date/time of <cFileName>.  If FALSE. (default),
then <cFileName> will be compiled only if it's date/time stamp
is later than the date/time stamp of it's associated. .OBJ file.

Notes:

If <cFileName> contains a full-path specification of a .PRG file, then the compiled .OBJ will be created in the same directory as the .PRG file unless the /o compiler switch is used to direct the output.

If <cFileName> does not contain a full path then the .PRG file must exist in the current directory or the directory established by DC_SETT('PDIR',<cPath>), SET PDIR TO <cPath> or PDIR=<cPath> (DCLIP.SYS).

If <cFileName> does not contain a full path or the /o compiler switch is not used, then the compiled .OBJ will be created in the directory established by DC_SETT('ODIR',<cPath>), SET ODIR TO <cPath> or ODIR=<cPath> (DCLIP.SYS).

Examples:

 accept 'Enter a file to edit and compile' TO cFile
 dc_editprg(cFile)
 DC_COMPILE(cFile,'/n/m/w/l')

Files:

_DCMAKE.PRG

See Also:

   COMPILE
   dc_objload()


dc_completeevents()

Process all events in the event queue

DC_CompleteEvents() is used to process all events in the event queue. Use this function in processing loops when it is necessary to react to window events to move the window or to affect the processing.

Syntax:

DC_CompleteEvents() -> nil

Returns:

Nil

Arguments:

None.

Examples:

FUNCTION XTest()

LOCAL lContinue := .t.

oBusyDlg := DC_BusyOn( SetAppWindow(), ;
                       {||WaitDialog(@lContinue,@oStatus)} )

DO WHILE !Eof() .AND. lContinue

  oStatus:setCaption('Processing Record ' + Alltrim(Str(n)))
  SKIP
  DC_CompleteEvents()

ENDDO

DC_BusyOff(oBusyDlg)

RETURN nil

* -------------------

STATIC FUNCTION WaitDialog( lContinue, oStatus )

LOCAL GetList[0], oBusyDlg, GetOptions

@ 0,0 DCSAY "Processing" FONT '20.Arial Bold' SAYSIZE 0

@ 2,0 DCSAY '' OBJECT oStatus COLOR GRA_CLR_BLUE FONT '12.Arial Bold' SIZE 30

@ 4,8 DCPUSHBUTTON CAPTION 'Cancel' ACTION {||lContinue := .F. } SIZE 9, 1.2

DCGETOPTIONS NOTITLEBAR HIDE

DCREAD GUI FIT EXIT PARENT @oBusyDlg OPTIONS GetOptions

RETURN oBusyDlg

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_clearevents()
   dc_saveevents()
   dc_restoreevents()


dc_configdialogbuttons()

Configure buttons in title bar area of dialog window

DC_ConfigDialogButtons() is used to configure the buttons in the titlebar area of a dialog window.<br><br>For example, the buttons can be configured to disable the Maximize button in a child window.

Syntax:

DC_ConfigDialogButtons( <oDlg>, ;
                        <nOption> ) -> nil

Arguments:

<oDlg> is the Dialog object to configure.

<nOption> is an option, defined in DCDIALOG.CH:

 DLG_BUTTON_HELP_NOMINMAX
 DLG_BUTTON_NONE
 DLG_BUTTON_DISABLEMAX

Examples:

DCREAD GUI EVAL ;
      {|o|DC_ConfigDialogButtons(o,DLG_BUTTON_DISABLEMAX)}

Files:

DCLIPX.LIB, DCLIPX.DLL


dc_copynew()

Copy only new files to another directory

DC_CopyNew() is used to copy a file or set of files to another directory only if they are newer than the sames files in the destination directory.<br><br> A dialog window will display the status of all files copied.

Syntax:

 DC_CopyNew( [<cFromSpec>], ;
             [<cToSpec>] ) -> lStatus

Returns:

 A logical .TRUE. if any files were copied.

Arguments:

<cFromSpec> is the specification of the file(s) to copy from.
If this argument is not given, then a dialog will be displayed
prompting the user for the file specification.

<cToSpec> is the specification of the directory to copy to.
If this argument is not given, then a dialog will be displayed
prompting the user for the directory specification.

Examples:

 DC_CopyNew('*.TXT','C:\express\sample')

Files:

_DCCOPYN.PRG, DCLIP1.DLL

See Also:

   COPYNEW


dc_count()

Count records in selected database

DC_Count() is used to count records from the currently selected database based on a set of conditions. As GUI dialog window is displayed for the user to select the conditions.

Syntax:

 DC_Count() -> lStatus

Returns:

 A logical .TRUE. if the count was not aborted.

Arguments:

 None.

Examples:

 . USE COLLECT
 . DC_Count()

Files:

_DCSUM.PRG, DCLIP2.DLL

See Also:

   COUNT


dc_create()

Create a new database

DC_Create() is used to create a new database from a menu in which the user is prompted for entering field names, types, lengths, etc.<br><br> The currently selected default DBE is used when the new database is created.<br><br><br><br>

Syntax:

 DC_Create( <cDataBase> ) -> lStatus

Returns:

 A logical .TRUE. if the database was successfully created.

Arguments:

<cDataBase> is the name of the new database to create.  If you
do not include an extension, then the default extension for the
currently selected database driver will be used.

Examples:

 . SET DBE TO FOXCDX
 . DC_Create('JUNK')

Files:

_DCFCSTR.PRG, DCLIP1.DLL

See Also:

   CREATE


dc_crindex()

Create an index file

DC_CRINDEX() is a high-level function that provides a user-interface menu for creating a new index file.<br><br>

Syntax:

 DC_CrIndex() -> lStatus

Returns:

 A logical .TRUE. if the index was created successfully, .FALSE.
 otherwise.

Arguments:

 None.

Examples:

 . USE COLLECT
 . DC_CrIndex()

Files:

_DCDBIND.PRG, DCLIP1.DLL

See Also:

   INDEX ON


dc_crtrun()

Run a text-based procedure in a new CRT Window

DC_CrtRun() is used to run a text-based procedure in a new CRT Window.<br><br> The function DC_CrtRunWindow() is used to store a pointer to any existing XbpCrt() class window to use. If this function returns anything other than an XbpCrt() object, then a new CRT window is created before the code block is evaluated and then destroyed after returning from the code block.

Syntax:

 DC_CrtRun( <bBlock>, ;
            [<cTitle>], ;
            [<cColorString>], ;
            [<oParent>], ;
            [<oOwner>], ;
            [<lUnique>], ;
            [<aOptions>], ;
            [<lModal>], ;
            [@<oCrt>], ;
            [<lSuspend>], ;
            [<lGui>] ) -> lStatus

Returns:

 A logical .TRUE. if the text procedure was executed successfully.

Arguments:

<bBlock> is the code block to evaluate after the CRT window
is created or selected.

<cTitle> is the title to place into the title bar of the CRT
window.

<cColorString> is the color to clear the CRT window.

<oParent> is the parent of the CRT window.  If this parameter is
not passed, then the parent will be AppDeskTop().

<oOwner> is the owner of the CRT window.  If this argument is
not passed, then the owner is the parent.

<lUnique> if .TRUE. will create the CRT window and run the
code block only if there is not a window already running with the
same code block.  The default is .FALSE.

<aOptions> is an array of display options:

   Element Type Description
   ------- ---- -----------------------------------------------
     [1]     N  Font Width (Default is 8)
     [2]     N  Font Height (Default is 12)
     [3]     C  Font Name (Default is Alaska Crt)
     [4]     N  Window Icon (Default is DC_IconDefault())
     [5]     N  Text Rows
     [6]     N  Text Columns

<lModal> if .TRUE. will make the CRT window MODAL if it is not
a child window.

@<oCrt> is the name of a variable to store a pointer to the
Crt Window object that is created.

<lSuspend> is RESERVED.

<lGui> is used to set the DC_Gui() flag.

Examples:

 . DC_CrtRun( {||DC_ChrSel()}, 'ASCII Chart', 'N/W' )

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_crtrunwindow()
   dc_crtwindow()
   dc_qout()
   dc_gui()


dc_crtrunwindow()

Set the CRT Window for DC_CrtRun()

DC_CrtRunWindow() is used to store a pointer to any existing XbpCrt() class window to use later with DC_CrtRun(). If this function returns anything other than an XbpCrt() object, then DC_CrtRun() will create a new window before the code block is evaluated and then destroyed after returning from the code block.

Syntax:

 DC_CrtRunWindow( [<oCrt>] ) -> oCrtWindow

Returns:

 A pointer to the previous CRT window.

Arguments:

<oCrt> is a pointer to an XbpCrt() class CRT window.

Examples:

 . oCrt := DC_CrtWindow()
 . DC_CrtRunWindow(oCrt)
 . DC_CrtRun( {||DC_ChrSel()}, 'ASCII Chart', 'N/W' )

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_crtrun()
   dc_crtwindow()
   dc_qout()


dc_crtwindow()

Create a Crt Window to be used later with DC_CrtRun()

DC_CrtWindow() is used to create a CRT Window which will be used later with DC_CrtRun().<br><br> The function DC_CrtRunWindow() is used to store a pointer to any existing XbpCrt() class window to use. If this function returns anything other than an XbpCrt() object, then a new CRT window is created before the code block is evaluated and then destroyed after returning from the code block.

Syntax:

 DC_CrtWindow( [<cTitle>], ;
               [<cColorString>] ) -> oCrtWindow

Returns:

 A pointer to the newly created CRT Window (an XbpCrt object).

Arguments:

<cTitle> is the title to place into the title bar of the CRT
window.

<cColorString> is the color to clear the CRT window.

Examples:

 . oCrt := DC_CrtWindow()
 . DC_CrtRunWindow(oCrt)
 . DC_CrtRun( {||DC_ChrSel()}, 'ASCII Chart', 'N/W' )

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_crtrunwindow()
   dc_qout()


dc_csv2array()

Export an array to a comma-delimted CSV file

DC_Csv2Array() imports a comma-delimited CSV file into a 2-dimensional array.

Syntax:

DC_Csv2Array( <cCsvFileName> ) -> aArray

Returns:

A 2-dimensional array.

Arguments:

<cCsvFileName> is the name of the file to import.

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_array2csv()


dc_csv2workarea()

Import a CSV file to an open work area

DC_Csv2WorkArea() loads a CSV file into a work area.<br><br>The top line of the CSV file must contain the field names that match the work area.

Syntax:

DC_Csv2WorkArea() -> <lStatus>

Returns:

A logical .TRUE. if file was successfully imported, .FALSE. otherwise.

Examples:

See the example in \exp19\samples\csv\csvimp2.prg.

Files:

_DCFUNCT.PRG, DCLIPX.DLL


dc_curpath()

Get the current dos directory

DC_CURPATH() reports the currently selected DOS directory for any specified drive.

Syntax:

DC_CurPath ( [<cDrive>] ) -> cDirectory

Returns:

 A character string representing the selected drive and directory.

Arguments:

<cDrive> is the drive to report the currently selected
directory. If no argument is given, then the currently selected
drive is the default.

Examples:

 PROCEDURE XTest()

 DC_Gui(.t.)

 dc_chdir('C:\ALASKA\XPPW32')
 DC_MsgBox( DC_CURPATH() )

 dc_chdir('\EXPRESS\SAMPLE')
 DC_MsgBox( DC_CURPATH('C:') )

 RETURN

Files:

_DCPATH.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_setdclip()
   dc_setdefault()


dc_dataconvert()

Convert a database to a different DBE driver

DC_DataConvert() is used to convert a database to use another DBE driver.

Syntax:

 DC_DataConvert( [<cFileName>], ;
                 [<cFromDBE>], ;
                 [<cToDBE>], ;
                 [<cExtension>] ) -> lStatus

Returns:

 A logical .TRUE. if the conversion was successful.

Arguments:

<cFileName> is the name of the database to convert.  If this
argument is not passed a GUI dialog window will be displayed to
enter information required.  Enter ALL to convert all databases
with a specified extension.

<cFromDBE> is the DBE to use to open <cFileName>.

<cToDBE> is the DBE to use to create the converted file.

<cExtension> is the extension to use when using ALL as the
file name

Examples:

 // convert all files that have a .DBT memo file.
 . DC_DataConvert('COLLECT','DBFNTX','FOXCDX','.DBT')

 // convert all files that have a .DBF extension
 . DC_DataConvert('ALL','DBFNTX','DBFCDX','.DBF')

Files:

_DCRDD.PRG, DCLIP2.DLL

See Also:

   DATACONVERT


dc_datarest()

Restore work areas

DC_DATAREST(aWork) will reopen all databases, indexes and relations from the array created by DC_DATASAVE(). This function is handy when it is necessary to insure that database work areas are restored to their original condition after calling a routine that may close files, open files, select different indexes or clobber relations.<br><br>

Syntax:

 DC_DataRest( <aWorkArea> ) -> lStatus

Returns:

 A logical .TRUE. if workareas were successfully restored.

Arguments:

<aWorkArea> is a multidimensional array created by the SAVE DATA
command or DC_DataSave() function.

Examples:

 . USE EXPRESS ALIAS XDOC VIA FOXCDX INDEX EXPRESS
 . SET TAG TO COMMAND
 . aWorkArea := DC_DataSave()
 . CLOSE ALL
 . DC_DataRest(aWorkArea)

Files:

_DCRDD.PRG, DCLIP2.DLL

See Also:

   dc_datasave()


dc_datasave()

Save info about all open workareas to an array

DC_DATASAVE() will store all work area info to an array.<br><br> DC_DATAREST(aWork) will reopen all databases, indexes and relations from the array created by DC_DATASAVE(). This function is handy when it is necessary to insure that database work areas are restored to their original condition after calling a routine that may close files, open files, select different indexes or clobber relations.<br><br>

Syntax:

 DC_DataSave() -> aWorkArea

Returns:

 A multidimensional array.

Arguments:

 None.

Examples:

 . USE EXPRESS ALIAS XDOC VIA FOXCDX INDEX EXPRESS
 . SET TAG TO COMMAND
 . aWorkArea := DC_DataSave()
 . CLOSE ALL
 . DC_DataRest(aWorkArea)

Files:

_DCRDD.PRG, DCLIP2.DLL

See Also:

   dc_datarest()


dc_dbchcreate()

Create a database or array pick-list object

DC_DBCHCREATE() is used to create a database pick-list object or an array pick-list object to be used with DC_DBCHOICE().<br><br> This function is used to create "fully-moused" database or array pick-lists.

Syntax:

DC_DbChCreate ( <aOptions>, ;
                <aColumns>, ;
                [<aTags>], ;
                [<aData>] ) -> aObject

Returns:

 A multi-dimensional array to be passed to DC_DBCHOICE() for
 pick-list operations.

Arguments:

<aOptions> is an array defining the pick-list window size,
color, function, and array data when browsing an array.

Element Type   Description
------- ----  -----------------------------------------------
   1     N     Start display row
   2     N     Start display column
   3     N     End display row
   4     N     End display column
   5     C     Heading at top of window
   6     C     Menubar at top or bottom of window.  The first
               character in each word will be highlighted
               or the first character after any tilde ~
               character will be highlighted.
   7     C     A color string for the box and lines
   8     C     A color string for the data items
   9     C     A color string for the data select bar
  10     C     A color string for column headings
  11     C     A color string for the menu bar at the bottom
               of the window.  This is a two-color string
               (separated by a comma).  The first color is
               the bar and words, the second is the highlight
               color.
  12     L     If .TRUE. then "Auto-Seek" mode will be enabled.
               Auto-Seek will cause the pick-list to
               automatically seek to the item whose index key
               matches the sequence of keys pressed.
  13  C/N/D/L  A value to include in a "One-To-Many" style
               pick-list.  The type of this value must match
               the index key of the database.  Only database
               items that match this value will be included
               in the display.  This is provided for compatability
               with previous versions.  Parameters 19/20 are
               recommended for one-to-many browses.
  14     L     If .TRUE. then a "Tagging" Column will be
               displayed.  All records or array elements which
               have been tagged will contain a check mark.  The
               operator may tag/untag records with the SPACE bar
               key, TAG records with the LEFT mouse key, or UNTAG
               records with the RIGHT mouse key.
  15     N     The INKEY() value of the key to assign as the
               Record Tagging key.  The default is 32 (Space bar).
  16     L     If .FALSE. will display menu at bottom.
               If .TRUE. will display menu at top (default).
  17     N     Starting array element to browse
  18     N     Subscript number of data array that is used for
               holding tags.  This is required if Tag Mode is
               enabled and you are browsing an array rather than
               a database.  The tags must all be initialized to
               a logical value.
  19  C/D/N/L  A value that defines the SCOPE TOP of the database
               for one-to-many browses.
  20  C/D/N/L  A value that defines the SCOPE BOTTOM of the
               database for one-to-many browses.
  21     A     An optional array of 10 elements.  Each element
               is a character string to display as the mouse
               "prompt" message when the mouse is placed over
               one of the 10 mouse buttons at the bottom of
               the window.  The 10 default messages are defined
               in the _DCDBCHO.PRG source code.

Note:  If color elements are not passed, then the system
       default colors will be used.

<aColumns> is a multi-dimensional array that defines the
columns in the pick-list window.  One sub-array is required
for each column in the window.

Element   Type    Description
-------  ------- --------------------------------------
   1       C      Expression to evaluate
       or  B      Code-Block to evaluate
       or  N      Array sub-element number (array browse mode)

   2       C      Column title

   3       N      Column width.  If 0, then column will
                  automatically size to expression output
                  width.

   4       C      Code Block to pass to SETCOLOR()
                  For example, this could be the name of a color
                  field in a database and would be passed as
                  follows: {||APPT_COLOR} .OR. {||'W+/B'}.

<aTags> is an optional array of record numbers which will
may be modified by the operator.  If no valid array name is
passed and the Tag Mode option was enabled in <aOptions>
then the DCTAGS public array will be used for storing the
record tags. If browsing an array, then the tags are handled
by including a sub-element in the array being browsed.

<aData> is an optional multi-dimensional array to browse.
If any value other than an array is passed then the current
database workarea will be browsed.  If tagging is enabled,
then one of the elements of each sub-array is used to hold
the logical tag value.

Examples:

 -- Example 1 --

 // Using DC_DBCHCREATE() / DC_DBCHOICE() as a main menu for
 // help database

 local aObject := ;
    DC_DBCHCREATE( { 0, 0, MaxRow(), 79, ' Help Menu ',;
                  ' Edit     View     Search     Print' },;
                   { { 'TYPE','Function Type', 15 } ,;
                     { 'COMMAND','Command Syntax' },;
                     { 'SHORT','Description' } } )
 local nInkey, lPaintScrn := lExplode := .t.

 do while  .t.

   select dchelp
   aObject := ;
       dc_dbchoice( aObject, @nInkey,, lPaintScrn, lExplode )
   cCode := chr(nInkey)
   store .f. TO lPaintScrn, lExplode

   do case

     case nInkey=27
       exit

     case nInkey <= -101
       dc_mousekey( { {MaxRow(),0,MaxRow(),9,'E'},;
                      {MaxRow(),11,MaxRow(),20,'V'},;
                      {MaxRow(),22,MaxRow(),29,'S'},;
                      {MaxRow(),31,MaxRow(),37,'P'} } )

     case cCode='E'
       do editmenu
     case cCode='V'
       do viewmenu
     case cCode='S'
       do searchmenu
     case cCode='P'
       do printmenu

   endcase

 enddo

 -- Example 2 --

 // Using DC_DBCHCREATE() / DC_DBCHOICE() to pick a printer
 // record.

 local nInkey
 local aObject := ;
   DC_DBCHCREATE( { 2,15,MAXROW()-1, 65, 'Select a Printer' } ,;
                          { {'PTR_DESC','Description'} ,;
                            {'STR(RECNO(),6)','Number' } } )
 DC_DBCHOICE( aObject, @nInkey )
 IF nInkey = K_ENTER
   RETURN RECNO()
 ELSE
   RETURN 0
 ENDIF

 -- Example 3 --

 // Using DC_DBCHCREATE() / DC_DBCHOICE() to create a
 // directory pick-list with an array for tagging files.

 local aObject, aDirectory := Directory('*.*'), nInkey, nChoice
 local i

 for i := 1 TO len(aDirectory)
   aadd( aDirectory[i], .f. )  // add element for tag
 next

 aObject := ;
   DC_DBCHCREATE( {2,7,20,73, ' Tag file(s) ',,,,,,,,,.t.,,.t.,,6},;
     { { 1,'Name',12 } ,;
       { 2,'Size',10 } ,;
       { 3,'Date',8 } ,;
       { 4,'Time',8 } ,;
       { 5,'Attr',5 } } ,, aDirectory )

 aObject := DC_DBCHOICE( aObject, @nInkey,, .f., .f. )
 for i := 1 to len(aDirectory)
   if aDirectory[i,6]  // tagged element
     if dc_msgbox(,,{aDirectory[i,1],'Delete File?'},,,,.t.)
       Ferase( aDirectory[i,1] )
     endif
   endif
 next

Files:

_DCDBCHOI.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_dbchoice()
   dc_readdpick()


dc_dbchoice()

A browse-style, moused, database/array pick-list

DC_DBCHOICE() is a database pick-list function that supports one-to-many style picklists, Auto-seeking operation, record tagging, and mouse.<br><br> DC_DBCHOICE() is used with an array object created by DC_DBCHCREATE().

Syntax:

DC_DbChoice ( <aObject>, ;
              @<nInkey>, ;
              [<cUdfName>], ;
              [<lPaintItems>], ;
              [<lPaintWindow>], ;
              [<lExit>], ;
              [<nStartRow>], ;
              [<aTags>] ) -> aObject

Arguments:

<aObject> is an array of window and field information created
by DC_DBCHCREATE().

@<nInkey> is a memory variable (passed by reference) to store
the value of the key hit or mouse-event used to exit the
pick-list.

<cUdfName> is a User defined function to call between
keystrokes.

<lPaintItems> if .TRUE. will repaint all items in the display.

<lPaintWindow> if .TRUE. will repaint the entire display window
and all items.

<lExit> if .TRUE. will exit after painting the window and/or
items. If .FALSE. then DC_DBCHOICE() will exit only if a key is
hit that is a non-navigation key.

<nStartRow> is the display row to place the select bar.

<aTags> is an optional array of record numbers which will
may be modified by the operator.  If no valid array name is
passed and the Tag Mode option was enabled in the <aObject>
then the DCTAGS public array will be used for storing the
record tags.

Examples:

 -- Example 1 --

 // Using DC_DBCHCREATE() / DC_DBCHOICE() as a main menu for
 // help database

  local aObject := ;
    dc_dbchcreate( { 0, 0, MaxRow(), 79, ' Help Menu ',;
                  ' Edit     View     Search     Print' },;
                   { { 'TYPE','Function Type' } ,;
                     { 'COMMAND','Command Syntax' },;
                     { 'SHORT','Description' } } )
 local nInkey, lPaintScrn := lExplode := .t.

 do while  .t.

   select dchelp
   aObject := ;
      DC_DBCHOICE( aObject, @nInkey,, lPaintScrn, lExplode )
   cCode := chr(nInkey)
   store .f. TO lPaintScrn, lExplode

   do case

     case nInkey=27
       exit

     case nInkey <= -101
       dc_mousekey( { {MaxRow(),0,MaxRow(),9,'E'},;
                      {MaxRow(),11,MaxRow(),20,'V'},;
                      {MaxRow(),22,MaxRow(),29,'S'},;
                      {MaxRow(),31,MaxRow(),37,'P'} } )

     case cCode='E'
       do editmenu
     case cCode='V'
       do viewmenu
     case cCode='S'
       do searchmenu
     case cCode='P'
       do printmenu

   endcase

 enddo

 -- Example 2 --

 // Using DC_DBCHCREATE() / DC_DBCHOICE() to pick a printer
 // record.

 local nInkey
 local aObject := ;
    DC_DBCHCREATE( { 2,15,MAXROW()-1, 65, 'Select a Printer' } ,;
                           { {'PTR_DESC','Description'} ,;
                             {'STR(RECNO(),6)','Number' } } )
 DC_DBCHOICE( aObject, @nInkey )
 IF nInkey = K_ENTER
   RETURN RECNO()
 ELSE
   RETURN 0
 ENDIF

Files:

_DCDBCHO.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_dbchcreate()


dc_dbcontinue()

Continue Locating a record in a set of Scoped Records

The function DC_DbLocate() defines a search condition for each work area that is the subject of a sequential search for matching records in that work area. The search is also initiated by DC_DbLocate() and continued using DC_DbContinue(). In this way all records in a work area matching a search condition can be found. <br><br>The function DC_DbContinue() moves the record pointer in the work area until a matching record is found. The matching record becomes the current record and DbContinue() returns the value.T. (true). The function Found() can also be used to test the result of a DbContinue(). If no matching record is found, the return value is .F. (false) and the record pointer is positioned after the last record. In this case, the function Eof() returns the value .T. (true). <br><br>

Syntax:

 DC_DbLocate( <bForCondition>, ;
             [<bWhileCondition>], ;
             [<nCount>], ;
             [<xRecordID>], ;
             [<lRest>] ) --> lFound

Returns:

 A logical value.

Arguments:

<bForCondition> is a code block which contains the search
condition as a logical expression. The record pointer is moved
to the next data record until <bForCondition> provides the
value .T. (true) or until the end of the file is reached.

<bWhileCondition> is an optional code block containing a
condition as a logical expression. As long as this code block
provides the value .T. (true), the search continues. The
operation terminates as soon as <bWhileCondition> returns .F.
(false).

The optional argument <nCount> specifies the number of records
searched beginning with the current record.

<xRecordID> is a record ID (for DBF files it is the record
number) which can be optionally specified. If specified, only
this record is searched.

The optional logical value <lRest> specifies whether all data
records of a work area are searched (<lRest>==.F. ), or only
the records from the current to the last record (<lRest>==.T. ).
The default value is .F. (false), meaning all data records are
searched.

Notes:

DC_DbLocate() can be used as a direct replacement for dbLocate() because all the parameters are simply passed on to dbLocate() if no scope is set.

Examples:

 . USE EXPRESS VIA FOXCDX INDEX EXPRESS
 . SET SCOPE TOP TO 'DC_F'
 . SET SCOPE BOTTOM TO 'DC_H'
 . ? DC_DbLocate({||syntax$'DC_G'})
.T.
 . ? DC_DbContinue()
.T.

Files:

_DCSCOPE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_setscope()
   CONTINUE
   dc_dblocate()


dc_dbcreate()

Create a database from structure in parallel-array format

DC_DBCREATE() will create a .DBF style database from a set of parallel arrays. This function is provided in lieu of the Xbase++ DBCREATE() function which builds a database from a ragged array. Sometimes it is more convenient to provide the data in four "parallel" arrays or four "sub" arrays that in "ragged" format.<br><br><br><br><br><br><br><br>

Syntax:

DC_DbCreate( <cFileName>, ;
             <aFields>, ;
             <aTypes>, ;
             <aLengths>, ;
             <aDecimals>, ;
             [<cDbe>] ) -> lStatus

Returns:

 .TRUE. if database is successfully created, .FALSE. otherwise.

Arguments:

<cFileName> is the name of the database to create.

<aFields> is an array of field names.  Each must be a character
value of no more than 10 characters and must start with an
Alphabet character.

<aTypes>  is a parallel array of field types.   Each must be a
character value with a length of 1.  Valid Types are:

 "C" - Character
 "D" - Date
 "L" - Logical
 "N" - Numeric
 "M" - Memo

<aLengths> is a parallel array of field lengths.  Each must be
a numeric value.

<aDecimals> is a parallel array of field decimals.  Each must
be a numeric value.

 <cDbe> is the name of the DBE to use to create the database.
 If no parameter is passed, then the default DBE will be used.

Examples:

 DC_DBCREATE( "CUSTOMER.DBF",;
              { "CUST_NAME","CUST_NMBR", "BALANCE" },;
              { "C", "C", "N" },;
              { 25, 5, 9 },;
              { 0, 0, 2 } )

Files:

_DCAREA.PRG, DCLIP1.DLL

See Also:

   dc_dbstruct()


dc_dbedit()

A Dual-Mode replacement for DBEDIT()

DC_DBEDIT() is a Dual-mode replacement for Dbedit(). When the GUI flag is ON, DC_DBEDIT() functions similiar to DbEdit() except that it is displayed in GUI mode. When the GUI flag is OFF, DC_DBEDIT() functions identical to DbEdit() except it is also activated by a mouse. The left button of the mouse is used to select the item in the window. The right button or double-clicking works identical to the ENTER key.

Syntax:

DC_DbEdit ( [<nTop>], ;
            [<nLeft>], ;
            [<nBottom>], ;
            [<nRight>], ;
            [<aColumns>], ;
            [<cUserFunc> | <bUserFunc>], ;
            [<acPicture>], ;
            [<acHeading>], ;
            [<acHeadSep>], ;
            [<acColSep>], ;
            [<acFootSep>], ;
            [<acFooting>] ) -> nil

Arguments:

<nTop>, <nLeft>, <nBottom>, <nRight> are the screen
text-based coordinates.

<cUserFunc> | <bUserFunc> is the name of an optional User-Defined
function to call on exception keystrokes.  See the Xbase++
documentation of ACHOICE() for more information on how to use
a UDF.  If the parameter is passed as a character string then
the function must be a PUBLIC, not STATIC function.

<aColumns> is an array whose elements may contain only
character strings. The character strings contain field names
or expressions which can be macro expanded to determine the
value displayed in each column.  DbEdit() displays a column
on screen for each element in <aColumns>.  If <aColumns> is
missing, all fields of the work area are displayed.

<acPicture> contains either a parallel array with PICTURE
formats for formatting values in each individual column or a
character string containing a PICTURE format for all columns.

<acHeading> contains either a parallel array of character
strings specifying the column headings for each individual
column or a character string to be used as the heading for
all columns.  Multiple row column headings are created when a
character string contains a semicolon. Where the semicolon
appears, the column heading is wrapped. When <acHeading> is
not included, the column headings are created from the
elements of <aColumns> .  If <aColumns> is also missing, the
field names in the work area are displayed as column headings.

<acHeadSep> contains either a parallel array of heading
separators to appear between the heading and data area for
each individual column, or a character expression which
defines the heading separator for all columns.  Chr(205) is
used as the default character and displays a double line.

<acColSep> contains either a parallel array of characters used
to create a separator between each column or a character
expression defining the heading separator for all columns.
Chr(179) is used as the default character displays a single
line.

<acFootSep> contains either a parallel array of footing
separators to appear between the data area and footer line
for each individual column or a character expression defining
the footer separator for all columns. If <acFootSep> is missing,
no footing separators are displayed.

<acFooting> contains either a parallel array of character
strings specifying the footer lines for each individual column
or a character string specifying the footer line for all
columns.   Multiple footer lines are created when a character
string contains a semicolon.   Where this semicolon appears,
the footer line is wrapped.   When <acFooting> is not included,
no footer lines are displayed.

Examples:

 PROCEDURE XTest()

 DC_Gui(.t.)

 USE collect NEW SHARED
 DC_DBEDIT( 5,10,20,75,,{||MyFunc()} )
 RETURN

 STATIC FUNCTION myfunc

 do case
   case lastkey() = asc('C')
     DC_MsgBox('C button pressed')
   case lastkey() = asc('D')
     DC_MsgBox('D button pressed')
   case lastkey() = asc('M')
     DC_MsgBox('M button pressed')
 endcase
 return nil

Files:

_DCDBED.PRG/.OBJ, DCLIPX.LIB

See Also:


dc_dbeval()

Evaluate set of expression for a database with active Escape

The database function DC_DbEval() evaluates a code block and increments the record pointer of a work area after each execution of the code block. When the function is used without the alias operator, it moves the record pointer in the current work area. By default, DC_DbEval() begins with the first logical record and evaluates the code block <bBlock> for each record until the last logical record is reached. The number of records for which the code block is evaluated can be influenced by the optional arguments and the setting of the TOP/BOTTOM scope by the DC_SetScope() function. <br><br>By specifying code blocks for <bForCondition> or <bWhileCondition>, a logical condition can be defined which must return the value .T. (true) for the code block <bBlock> to be evaluated. The <bForCondition> code block is evaluated for all data records. When it returns .T. (true), <bBlock> is executed. When <bWhileCondition> is specified, <bBlock> is only executed until <bWhileCondition> returns .F. (false), causing DbEval() to terminate. <br><br>Alternatively the number of records can be explicitly determined with <nCount> or <lRest> . Specifying <xRecordID> positions the record pointer on this record and the code block <bBlock> is evaluated for this and following records. <br><br>DC_DbEval() passes no arguments to the code blocks.

Syntax:

DC_DbEval ( <bBlock>, ;
            [<bForCondition>], ;
            [<bWhileCondition>], ;
            [<nCount>], ;
            [<xRecordID>], ;
            [<lRest>], ;
            [<lAutoLock>], ;
            [<lEscapeKey>] ) -> NIL

Returns:

NIL.

Arguments:

 <bBlock> contains a code block which is executed for each data
 record.

 <bForCondition> is an optional code block containing a condition
 as a logical expression. <bBlock> is only executed for the data
 records where <bForCondition> returns the value .T. (true).

 <bWhileCondition> is an optional code block containing a condition
 as a logical expression. DbEval() terminates as soon as
 <bWhileCondition> returns the value .F. (false).

 The optional argument <nCount> specifies the number of records
 for which <bBlock> is evaluated beginning with the current data
 record.

 The optional argument <xRecordID> specifies a record ID (for
 DBF files it is the record number). If <xRecordID> is specified,
 the evaluation of <bBlock> begins with the specified record.

 The logical value <lRest> optionally specifies whether <bBlock>
 is evaluated for all records of a work area (<lRest>==.F. ),
 or only for the records from the current to the last record
 (<lRest>==.T. ). The default value is .F. (false), indicating
  that <bBlock> is evaluated for all data records.

 <lAutoLock> if .TRUE. will lock the record before evaluating
 <bBlock>.  The default is .FALSE.

 <lEscapeKey> if .TRUE. will terminate the operation if the
 user presses the ESCape key.

Examples:

#command CLEAN ;
         [FOR <for>] ;
         [WHILE <while>] ;
         [<autolock:AUTOLOCK>] ;
         [<escapekey:ESCAPEKEY>]
  => ;
         DC_DBEVAL( {||clean()}, <{for}>, <{while}>,,, ;
                     <.autolock.>,<.escapekey.> )

DC_SetScope(0,'SMITH')
DC_SetScope(1,'ROGERS')

CLEAN FOR SHIP_DATE < DATE() AUTOLOCK ESCAPEKEY

Files:

_DCEVAL.PRG/.OBJ, DCLIPX.LIB


dc_dbfile()

Open a database file in a work area

DC_DBFILE() is used to open a database file in a manner that will prevent runtime errors. If the file can't be found, the user will be prompted to enter a directory path to search, or to abort.<br><br> If a structure array is passed then the behavior of DC_DBFILE() is as follows:<br><br> 1. If the database is not found in the specified or default directory, it will be created from the contents of the array.<br><br> 2. If the database is opened but any of the fields do not match the structure of the passed array, then the database structure will be updated to the array structure and the old data will be retained.<br><br>

Syntax:

DC_DbFile( [<cDirectory>], ;
            <cDataFile>, ;
           [<lUserPrompt>], ;
           [<lExclusive>], ;
           [<nWait>], ;
           [<cDbe>], ;
           [<lReOpen>], ;
           [<aStructure>], ;
           [<cAlias>], ;
           [<lNoErrorDisp>], ;
           [<lCreateDbf>], ;
           [@<lStruUpdated>], ;
           [<lStruMessage>] ) -> lStatus

Returns:

 Logical .TRUE. if the file is opened, .FALSE. otherwise.

Arguments:

<cDirectory> is the directory to search for the database file.
If no argument is given or a null ("") argument is passed, then
the current default directory (SET DEFAULT) will be search,
followed by the current path directory (SET PATH).

<cDataFile> is the name of the database to open.  If the file
extension is not included, then the default extension for the
designated DBE is used.

<lUserPrompt> will pop-up a menu to prompt the user if the file
cannot be found.

If <lExclusive> is .TRUE., the file will be opened in
EXCLUSIVE, mode, if .FALSE. it will be opened in SHARED mode.
If no argument is given the file will be opened in the default
system mode.

<nWait> is the number of seconds to wait if a SHARED file
cannot be opened until the user is notified of the error.  ( 0
- wait forever ).

<cDbe> is the Database Driver to use.  If no argument is given,
then the currently selected DBE will be used.

<lReOpen> if .TRUE. will reopen the file in the current work
area even if it is already opened in another work area.

<aStructure> multi-dimensional array that contains the
structure of the data base.  This array is only required in
the event that the database could not be found or if you
want to update any existing database to the new structure.
A new database will be created from the information in the
array.  If a code block is passed instead of an array, then it
will be evaluated.  The code block must return an array of the
same structure as <aStructure>. If a fifth element is included
in each sub-array, then a single-record will be appended to
the newly created database with the default information in
element 5.

Element   Type    Length   Description
-------   ----    ------   ----------------------------
  [1]      C         1     Field Name
  [2]      C         1     Field Type (C,D,N,L,M)
  [3]      N         4     Field Length
  [4]      N         2     Field Decimals
  [5]     Any       Any    Field Default value.  Must be
                           same type as Field Type.

<cAlias> is the alias to assign to the work area.  If no
argument is given, then the name of the database (less the
extension) will be used as the alias.

<lNoErrorDisp> if .TRUE. will suppress any error window output
in the event that the file cannot be opened.  If .FALSE.
(default) then errors will be displayed.

<lCreateDbf> if .TRUE. (default) will create the database
from the contents of <aStructure> if the database does not
exist, otherwise if .FALSE., the database will not be
created.

@<lStruUpdated> is a logical variable (passed by reference).
If the database structure was updated, this variable will be
set to .TRUE., otherwise it will be set to .FALSE.

<lStruMessage> if .TRUE. will prompt the user before updating
the structure.  IF .FALSE. the structure will be updated with
no prompt.

Examples:

local aStructure := ;
  {{'DBF_NAME','C',8,0},;
   {'DESC','C',30,0},
   {'QUERY','C',1000,0}}
if !DC_DBFILE( DC_SETDCLIP(),'DCQUERY.DBF',.t.,,,'DBFNTX',,;
    aStructure)
  return .F.
endif

Files:

_DCDBFIL.PRG, DCLIP1.DLL

See Also:

   dc_usearea()
   USE


dc_dbfile2record()

Copy a file to a record object.

DC_DbFile2Record() is used to create a record object from a file that was saved by DC_DbRecord2File().<br><br><br><br>

Syntax:

DC_DbFile2Record( <cFileName> ) -> oRecord

Returns:

A record object.

Arguments:

<cFileName> is the full path name of the file.

Notes:

A work area must be opened and the structure of the database inthe work area must be the same as the structure of the databaserecord that was saved.

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_dbrecord()
   dc_dbrecord2file()


dc_dbfname()

Get the full path database name of an open work area

DC_DBFNAME() returns the full file name of the database file for any work area.<br><br><br><br>

Syntax:

 DC_DbfName ( [<nArea>] ) -> cDbfFileName

Returns:

 A character string.

Arguments:

<nArea> is the work area.  If no argument is given, then the
current selected work area is default.

Examples:

 . select 2
 . use C:\DCLIP3\DCPRINT
 . select 4
 . use F:\CUSTOMER\INVOICE
 . ? DC_DBFNAME(2)
 C:\DCLIP3\DCPRINT.DBF
 . ? DC_DBFNAME(4)
 F:\CUSTOMER\INVOICE.DBF

Files:

_DCAREA.PRG, DCLIP1.DLL

See Also:

   dc_dbfile()
   dc_usearea()
   USE


dc_dbfsel()

Select a database from a picklist of open files

DC_DBFSEL() will pop-up a picklist of all work areas and display the alias and database file name open in each work area. It will also allow the user to select an unused work area to open a new database.<br><br>

Syntax:

 DC_DbfSel() -> nWorkArea

Returns:

 The numeric value of the work area selected.

Arguments:

 None.

Examples:

 . DC_DbfSel()

Files:

_DCDBFIL.PRG, DCLIP1.DLL

See Also:


dc_dbgather()

Gather data from a Record Object to the current data record

DC_DbGather() is used to gather the data in the iVars of a record object into the current record of the currently used database, or to create a new record.<br><br><br><br>

Syntax:

DC_DbGather( <oRecord>, ;
             [<lNew>], ;
             [<lCommit>], ;
             [<bLock>], ;
             [<cRecNoField> ) -> <lStatus>

Returns:

An array.

Arguments:

<oRecord> is a record object.

<lNew> if .TRUE. will append a new record.  The default is .FALSE.

<lCommit> if .TRUE. will dbCommit() the change to disk. The
default is .FALSE.

<bLock> is an optional code block which is called to determine
how a new record is added.  The default is to append a new record
to the database.  <bLock> can be used to override the default
behavior.  This can be used to reuse deleted or blank records
instead of always appending a new record.

<cRecNoField> isTthe name of a numeric field that contains the
current record number.  It will be updated with the RecNo().
This is handy when a record number field is required in SQL
queries and it needs to be maintained.

Examples:

FUNCTION XTest()

LOCAL oRecord

USE COLLECT

oRecord := COLLECT->(DC_DbRecord():new())
COLLECT->(DC_DbScatter(oRecord))

@ 1,1 DCSAY 'Description' GET oRecord:descript
@ 2,1 DCSAY 'Type' GET oRecord:type
@ 3,1 DCSAY 'Sub-Type' GET oRecord:subtype

DCREAD GUI

COLLECT->(DC_DbGather(oRecord))

RETURN nil

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_dbrecord()
   dc_dbscatter()
   dc_dbgatherlog()


dc_dbgatherlock()

Get-Set function to set default lock behavior for DC_DbGather()

DC_DbGatherLock() is a Get-Set function that is used to post a code block which is read by DC_DbGather(). This is the default value for the <bLock> parameter that is passed to DC_DbGather().<br><br><br><br><br><br>

Syntax:

DC_DbGatherLock( [<bLock>] -> bOldLock

Returns:

A code block or a NIL.

Arguments:

<bLock> is an optional code block which is called to determine
how a new record is added.  The default is to append a new record
to the database.  <bLock> can be used to override the default
behavior.  This can be used to reuse deleted or blank records
instead of always appending a new record.

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_dbrecord()
   dc_dbgather()


dc_dbgatherlog()

Establish logging data for dc_dbgather()

DC_DbGatherLog() is used to establish the name, alias and dbe of the log file when wishing to log all DC_DbGather() transactions.<br><br>DC_DbGatherLogBrowse() will browse the log file and display 2 windows that are used to show the contents of the record before and after the write operation. <br><br>

Syntax:

DC_DbGatherLog( <aParams> ) -> <aParams>

Returns:

An array.

Arguments:

<aParams> is an array of 6 elements.

Element  Type  Description
-------  ----  --------------------------------------------------------
  [1]     C    The name of the logging database  Default is 'DATALOG.DBF'

  [2]     C    The alias of the logging database. Default is 'DATALOG'

  [3]     C    The DBE of the logging database. Defaultis dbeSetDefault().

  [4]     A    An array of database aliases to exclude or include from logging.
               This may be a single dimensional array of only aliases (for
               logging if any field changed) or a multi dimensional array
               of aliases and field names (for logging if only one or more of
               specified fields changed).

  [5]     B    A code block to evaluate.  This code block must return a
               character string to store in the "LOGIN" field of the
               logging file.

  [6]     L    Array (element 4) is list of included aliases, otherwise it
               is a list of excluded databases. Default is .FALSE.

Examples:

Look at the sample program in \exp19\samples\dbrecord\logging.prg.

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_dbgather()
   dc_dbrecord()
   dc_dbscatter()


dc_dbgatherlogbrowse()

Browse the dc_dbgatherlog() database

DC_DbGatherLogBrowse() will browse the log file and display 2 windows that are used to show the contents of the record before and after the write operation.<br><br><br><br>

Syntax:

DC_DbGatherLogBrowse() -> nil

Returns:

Nil

Arguments:

None.

Examples:

See the sample program in \exp19\samples\dbrecord.

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_dbgatherlog()
   dc_dbgather()
   dc_dbrecord()
   dc_dbscatter()


dc_dbgobottom()

Go to the Bottom of a set of Scoped Records

DC_DBGOBOTTOM() is used to go to the first record in a group of "scoped" records. Scopes are set via the DC_SetScope() function. If a scope is not set or the ADSDBE is being used as the data driver for the current workarea, then DC_DBGOBOTTOM() simply calls dbGoBottom() therefore it can be used as a replacement for dbGoBottom().<br><br>

Syntax:

DC_DbGoBottom () -> nil

Returns:

 Nil.

Arguments:

 None.

Notes:

Examples:

 #include 'dcdialog.ch'
 #include 'appevent.ch'

 PROCEDURE XTest()

 LOCAL GetList := {}, oBrowse, aPres, cScopeTop, cScopeBot

 USE ..\XDOC\EXPRESS INDEX ..\XDOC\EXPRESS.CDX ;
     VIA FOXCDX ALIAS XDOC

 OrdSetFocus('COMMAND')
 DC_KeyStat(.t.)

 @ 3,1 DCBROWSE oBrowse ALIAS 'XDOC' ;
   SIZE 77,11.8 ;
   FREEZELEFT {1}

 DCBROWSECOL FIELD XDOC->command ;
   HEADER "Command" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->type  ;
   HEADER "Type" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->short ;
   HEADER "Short Description" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->module ;
   HEADER "Module" PARENT oBrowse ;

 DCBROWSECOL FIELD XDOC->category ;
   HEADER "Category" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->see_also ;
   HEADER "See Also" PARENT oBrowse

 DCREAD GUI ;
   FIT ;
   ADDBUTTONS ;
   TITLE 'Browse Scoping Demo' ;
   EVAL {||_SetNavBlocks(oBrowse),;
           DC_SetScope(0,'DC_G'),;
           DC_SetScope(1,'DC_K'),;
           DC_DbGoTop(),;
           oBrowse:RefreshAll() }

 RETURN

 /* -------------------- */

 STATIC PROCEDURE _SetNavBlocks( oBrowse )

 oBrowse:skipBlock     := {|n| DC_DbSkip(n)    }
 oBrowse:goTopBlock    := {| | DC_DBGoTop()    }
 oBrowse:goBottomBlock := {| | DC_DBGOBOTTOM() }
 oBrowse:phyPosBlock   := {| | Recno()         }
 oBrowse:posBlock      := {| | DC_KeyNo()      }
 oBrowse:lastPosBlock  := {| | DC_KeyCount()   }
 oBrowse:firstPosBlock := {| | 1               }

 RETURN

Files:

_DCSCOPE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_setscope()


dc_dbgoposition()

Moves the record pointer to a percent position in a work area

DC_DBGOPOSITION() is a replacement (wrapper) for the Xbase++ function dbGoPosition(). This corrects a problem in dbGoPosition() in which the record pointer can be moved to a deleted or filtered record thereby causing deleted or filtered records to appear in a browse when the vertical scroll thumb is used.<br><br>

Syntax:

DC_DbGoPosition( <nPercent> ) -> nil

Returns:

 NIL

Arguments:

<nPercent> is a numeric value in the range between 0 and 100.
Zero is equivalent to the first record and 100 indicates the
last record in a work area.

Notes:

Examples:

 #include 'dcdialog.ch'
 #include 'appevent.ch'

 PROCEDURE XTest()

 LOCAL GetList := {}, oBrowse, aPres

 USE ..\XDOC\EXPRESS INDEX ..\XDOC\EXPRESS.CDX ;
     VIA FOXCDX ALIAS XDOC

 OrdSetFocus('COMMAND')

 @ 3,1 DCBROWSE oBrowse ALIAS 'XDOC' ;
   SIZE 77,11.8 ;
   FREEZELEFT {1}

 DCBROWSECOL FIELD XDOC->command ;
   HEADER "Command" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->type  ;
   HEADER "Type" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->short ;
   HEADER "Short Description" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->module ;
   HEADER "Module" PARENT oBrowse ;

 DCBROWSECOL FIELD XDOC->category ;
   HEADER "Category" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->see_also ;
   HEADER "See Also" PARENT oBrowse

 DCREAD GUI ;
   FIT ;
   ADDBUTTONS ;
   EVAL {||_SetNavBlocks(oBrowse),;
           DC_DbGoTop(),;
           oBrowse:RefreshAll() }

 RETURN

 /* -------------------- */

 STATIC PROCEDURE _SetNavBlocks( oBrowse )

 oXbp:firstPosBlock := {| | 1 }
 oXbp:lastPosBlock  := {| | 100 }
 oXbp:PosBlock      := {| |DC_DbPosition()   }
 oXbp:GoPosBlock    := {|n|DC_DbGoPosition(n)}
 oXbp:skipBlock     := {|n|DC_DbSkipper(n)   }
 oXbp:goTopBlock    := {| |DC_DbGoTop()      }
 oXbp:goBottomBlock := {| |DC_DbGoBottom()   }
 oXbp:phyPosBlock   := {| |Recno()           }

 RETURN

Files:

_DCSCOPE.PRG/.OBJ, DCLIPX.LIB


dc_dbgotop()

Go to the Top of a set of Scoped Records

DC_DBGOTOP() is used to go to the first record in a group of "scoped" records. Scopes are set via the DC_SetScope() function. If a scope is not set or the ADSDBE is the data driver in the current workarea, then DC_DBGOTOP() simply calls dbGoTop() therefore it can be used as a replacement for dbGoTop(). <br><br>

Syntax:

DC_DbGoTop () -> nil

Returns:

 Nil.

Arguments:

 None.

Notes:

Examples:

 #include 'dcdialog.ch'
 #include 'appevent.ch'

 PROCEDURE XTest()

 LOCAL GetList := {}, oBrowse, aPres, cScopeTop, cScopeBot

 USE ..\XDOC\EXPRESS INDEX ..\XDOC\EXPRESS.CDX ;
     VIA FOXCDX ALIAS XDOC

 OrdSetFocus('COMMAND')
 DC_KeyStat(.t.)

 @ 3,1 DCBROWSE oBrowse ALIAS 'XDOC' ;
   SIZE 77,11.8 ;
   FREEZELEFT {1}

 DCBROWSECOL FIELD XDOC->command ;
   HEADER "Command" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->type  ;
   HEADER "Type" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->short ;
   HEADER "Short Description" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->module ;
   HEADER "Module" PARENT oBrowse ;

 DCBROWSECOL FIELD XDOC->category ;
   HEADER "Category" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->see_also ;
   HEADER "See Also" PARENT oBrowse

 DCREAD GUI ;
   FIT ;
   ADDBUTTONS ;
   TITLE 'Browse Scoping Demo' ;
   EVAL {||_SetNavBlocks(oBrowse),;
           DC_SetScope(0,'DC_G'),;
           DC_SetScope(1,'DC_K'),;
           DC_DbGoTop(),;
           oBrowse:RefreshAll() }

 RETURN

 /* -------------------- */

 STATIC PROCEDURE _SetNavBlocks( oBrowse )

 oBrowse:skipBlock     := {|n| DC_DbSkip(n)    }
 oBrowse:goTopBlock    := {| | DC_DBGOTOP()    }
 oBrowse:goBottomBlock := {| | DC_DbGoBottom() }
 oBrowse:phyPosBlock   := {| | Recno()         }
 oBrowse:posBlock      := {| | DC_KeyNo()      }
 oBrowse:lastPosBlock  := {| | DC_KeyCount()   }
 oBrowse:firstPosBlock := {| | 1               }

 RETURN

Files:

_DCSCOPE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_setscope()


dc_dblocate()

Locate a record in a set of Scoped Records

DC_DBLOCATE() is used to LOCATE a record in a group of "scoped" records. Scopes are set via the DC_SetScope() function. This functions identical to the Xbase++ dbLocate() function except the locate is accomplished only within the set of scoped records. If no scope is set, then the parameters are passed on to dbLocate().<br><br>

Syntax:

 DC_DbLocate( <bForCondition>, ;
             [<bWhileCondition>], ;
             [<nCount>], ;
             [<xRecordID>], ;
             [<lRest>] ) --> lFound

Returns:

 A logical value.

Arguments:

<bForCondition> is a code block which contains the search
condition as a logical expression. The record pointer is moved
to the next data record until <bForCondition> provides the
value .T. (true) or until the end of the file is reached.

<bWhileCondition> is an optional code block containing a
condition as a logical expression. As long as this code block
provides the value .T. (true), the search continues. The
operation terminates as soon as <bWhileCondition> returns .F.
(false).

The optional argument <nCount> specifies the number of records
searched beginning with the current record.

<xRecordID> is a record ID (for DBF files it is the record
number) which can be optionally specified. If specified, only
this record is searched.

The optional logical value <lRest> specifies whether all data
records of a work area are searched (<lRest>==.F. ), or only
the records from the current to the last record (<lRest>==.T. ).
The default value is .F. (false), meaning all data records are
searched.

Notes:

DC_DbLocate() can be used as a direct replacement for dbLocate() because all the parameters are simply passed on to dbLocate() if no scope is set.

Examples:

 . USE EXPRESS VIA FOXCDX INDEX EXPRESS
 . SET SCOPE TOP TO 'DC_F'
 . SET SCOPE BOTTOM TO 'DC_H'
 . ? DC_DbLocate({||syntax$'DC_G'})
.T.

Files:

_DCSCOPE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_setscope()
   dc_dbcontinue()


dc_dbrecord2file()

Copy a record object to a file

DC_DbRecord2File() is used to copy a record object that was created by DC_DbRecord() to a file.<br><br><br><br>

Syntax:

DC_DbRecordCompare( <oRecord1>, <oRecord2> ) -> lStatus

Returns:

A TRUE if the contents of the record objects are exactly equal,
otherwise FALSE.

Arguments:

<oRecord> is an object created by DC_DbRecord().

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_dbrecord()
   dc_dbfile2record()


dc_dbrecordclone()

Clone a Database Record Object

DC_DbRecordClone() will create a clone of a record object.<br><br><br><br>

Syntax:

DC_DbRecordClone(oRecord) -> <oNewRecord>

Returns:

A record object.

Arguments:

<oRecord> is a record object created by DC_DbRecord().

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_dbrecord()


dc_dbrecordcompare()

Compare two record objects created by DC_DbRecord()

DC_DbRecordCompare() is used to compare the contents of two record objects created by DC_DbRecord().<br><br><br><br>

Syntax:

DC_DbRecordCompare( <oRecord1>, <oRecord2> ) -> lStatus

Returns:

A TRUE if the contents of the record objects are exactly equal,
otherwise FALSE.

Arguments:

<oRecord1> and <oRecord2> are record objects created by
DC_DbRecord().

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_dbrecord()


dc_dbrecordcopy()

Copy a Database Record Object

DC_DbRecordCopy() will copy the contents of a record object that was created by DC_DbRecord() into another record object.<br><br><br><br>

Syntax:

DC_DbRecordCopy( <oRecordFrom>, <oRecordTo> ) -> nil

Returns:

Nil.

Arguments:

<oRecordFrom> is a record object created by DC_DbRecord().

<oRecordTo> is a record object that contains fields of the same
names as <oRecordFrom>.  Only field names of the same name and
type will be copied, all others will be ignored.

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_dbrecord()
   dc_dbscatter()
   dc_dbgather()
   dc_dbrecordcompare()


dc_dbrecordedit()

An editor for a record object

DC_DbRecordEdit() is a gui editor for modifying the contents of a record object.

Syntax:

DC_DbRecordEdit( <oRecord> ) -> lUpdated

Returns:

A logical .T. if the record was updated.

Arguments:

<oRecord> is a record object created by DC_DbRecord().

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_dbrecord()


dc_dbrecordisempty()

Test if a record object is empty

DC_DbRecordIsEmpty() will test if all fields of a record object are empty.<br><br><br><br>

Syntax:

DC_DbRecordIsEmpty(oRecord) -> <lStatus>

Returns:

A logical .TRUE. if all fields are empty, .FALSE. otherwise.

Arguments:

A record object that was created with DC_DbRecord().

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_dbrecord()


dc_dbrecordtrim()

Trims all character string values in a record object

DC_DbRecordTrim() is used to trim the trailing spaces off all character string values in a record object created with DC_DbRecord().

Syntax:

DC_DbRecordTrim( <oRecord> ) -> nil

Returns:

Nil

Arguments:

<oRecord> is a record object that was created with DC_DbRecord()
and filled with DC_DbScatter().

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_dbrecord()
   dc_dbscatter()


dc_dbscatter()

Scatter data from current record to a Record Object

DC_DbScatter() is used to scatter the data in all fields of the currently selected record into the iVars of a record object previously created by DC_DbRecord().<br><br>Two additional iVars are added to the record object:<br><br>RECORD_NUMBER - A numeric container for the current record number that is set when DC_DbScatter() is used.<br><br>RECORD_DELETED - A logical container for the Deleted() flag is set when DC_DbScatter() is used.<br><br><br><br>

Syntax:

DC_DbScatter( <oRecord> ) -> <oRecord>

Returns:

A pointer to the passed in record object.

Arguments:

<oRecord> is a record object.

Examples:

FUNCTION XTest()

LOCAL oRecord

USE COLLECT

oRecord := COLLECT->(DC_DbRecord():new())
COLLECT->(DC_DbScatter(oRecord))

@ 1,1 DCSAY 'Description' GET oRecord:descript
@ 2,1 DCSAY 'Type' GET oRecord:type
@ 3,1 DCSAY 'Sub-Type' GET oRecord:subtype

DCREAD GUI

COLLECT->(DC_DbGather(oRecord))

RETURN nil

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_dbrecord()
   dc_dbgather()


dc_dbseek()

Seek a record in a set of Scoped Records

DC_DBSEEK() is used to SEEK a record in a group of "scoped" records. Scopes are set via the DC_SetScope() function. This functions identical to the Xbase++ dbSeek() function except if the record is not found or is outside the range of the scope, it behaves as follows:<br><br> 1. If the record is not found the record pointer is placed at Eof() and a .FALSE. is returned.<br><br> 2. If the record is found but the indexkey() value is less than the top scope, the record pointer is placed at the beginning record of the scope and a .FALSE. is returned.<br><br> 3. If the record is found but the indexkey() value is greater than the bottom scope, the record pointer is placed at the last record of the scope and a .FALSE. is returned.<br><br> 4. If the record is found and the indexkey() value is within the range of the top and bottom scope, the record pointer is placed at the found record and a .TRUE. is returned.<br><br> If no scope is set or the ADSDBE is used as the data driver for the current workarea DC_DbSeek() simply calls dbSeek() therefore it can be used as a replacment for dbSeek().<br><br>

Syntax:

 DC_DbSeek ( [<xValue>], ;
             [<lSoftSeek>], ;
             [<cIndexTag>], ;
             [<lSeekLast>] ) -> lStatus

Returns:

 A logical value.

Arguments:

<xValue> is any value of the same type as the index key for
the selected order.

<lSoftSeek> if .TRUE. will perform a softseek. .FALSE. is default.

<cIndexTag> is the Index Tag to select for the seek.  The default
is the current order.

<lSeekLast> if .TRUE. will seek the last record that matches <xValue>.
The default is .FALSE.

Examples:

 . USE EXPRESS VIA FOXCDX INDEX EXPRESS
 . SET SCOPE TOP TO 'DC_F'
 . SET SCOPE BOTTOM TO 'DC_H'
 . ? DC_DbSeek('DC_G')
.T.
 . ? DC_DbSeek('DC_R')
.F.

Files:

_DCSCOPE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_setscope()


dc_dbskip()

Skip records in a set of Scoped Records

DC_DBSKIP() is used to SKIP <n> records in a group of "scoped" records. Scopes are set via the DC_SetScope() function. If a scope is not set, then DC_DBSKIP() simply calls dbSkip() therefore it can be used as a replacement for dbSkip().<br><br>

Syntax:

DC_DbSkip ( [<nRecords>] ) -> nil

Returns:

 The actual number of records that were skipped.  This number may
 be less than the number of records requested in the event that
 the first or last record in the scoped group was encountered.

 DC_DBSKIP() will not skip past the bottom record or previous
 the top record in a scoped group.

Arguments:

<nRecords> is any positive or negative value.

Notes:

Examples:

 #include 'dcdialog.ch'
 #include 'appevent.ch'

 PROCEDURE XTest()

 LOCAL GetList := {}, oBrowse, aPres, cScopeTop, cScopeBot

 USE ..\XDOC\EXPRESS INDEX ..\XDOC\EXPRESS.CDX ;
     VIA FOXCDX ALIAS XDOC

 OrdSetFocus('COMMAND')
 DC_KeyStat(.t.)

 @ 3,1 DCBROWSE oBrowse ALIAS 'XDOC' ;
   SIZE 77,11.8 ;
   FREEZELEFT {1}

 DCBROWSECOL FIELD XDOC->command ;
   HEADER "Command" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->type  ;
   HEADER "Type" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->short ;
   HEADER "Short Description" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->module ;
   HEADER "Module" PARENT oBrowse ;

 DCBROWSECOL FIELD XDOC->category ;
   HEADER "Category" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->see_also ;
   HEADER "See Also" PARENT oBrowse

 DCREAD GUI ;
   FIT ;
   ADDBUTTONS ;
   TITLE 'Browse Scoping Demo' ;
   EVAL {||_SetNavBlocks(oBrowse),;
           DC_SetScope(0,'DC_G'),;
           DC_SetScope(1,'DC_K'),;
           DC_DbGoTop(),;
           oBrowse:RefreshAll() }

 RETURN

 /* -------------------- */

 STATIC PROCEDURE _SetNavBlocks( oBrowse )

 oBrowse:skipBlock     := {|n| DC_DBSKIP(n)    }
 oBrowse:goTopBlock    := {| | DC_DbGoTop()    }
 oBrowse:goBottomBlock := {| | DC_DbGoBottom() }
 oBrowse:phyPosBlock   := {| | Recno()         }
 oBrowse:posBlock      := {| | DC_KeyNo()      }
 oBrowse:lastPosBlock  := {| | DC_KeyCount()   }
 oBrowse:firstPosBlock := {| | 1               }

 RETURN

Files:

_DCSCOPE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_setscope()
   dc_bof()
   dc_eof()


dc_dbskipunique()

Skip to the next unique record

DC_DBSKIPUNIQUE() is used to SKIP to the next record in the database that is unique within the controlling index.<br><br>

Syntax:

DC_DbSkip () -> nil

Returns:

 Nil.

Arguments:

None.

Examples:

 /* This example will load an array with every city in
    the database */

 PROCEDURE XTest()

 LOCAL aCity[0]

 dbeSetDefault('FOXCDX')
 USE xtest INDEX xtest
 OrdSetFocus('CITY')

 DO WHILE !Eof()
   AAdd( aCity, XTEST->city )
   DC_DbSkipUnique()
 ENDDO

 RETURN aCity

Files:

_DCSCOPE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_dbskip()
   dc_bof()
   dc_eof()


dc_dbstru()

Display the structure of the selected database

DC_DbStru() is used to display the structure of the selected database file. A GUI dialog window displays the structure in a scrollable window with options to Print or save to a File.

Syntax:

 DC_DbStru() -> cFieldName

Returns:

 The name of the field selected by the user, a character string.

Arguments:

 None.

Examples:

 . USE COLLECT
 . DC_DbStru()

Files:

_DCDBSTR.PRG, DCLIP1.DLL

See Also:

   DISPLAY STRUCTURE
   dc_dbstruw()


dc_dbstruct()

Get the structure of a database in various formats

DC_DBSTRUCT() is similar to the Xbase++ DBSTRUCT() function, except that it returns the structure in an arrays of various formats.<br><br><br><br><br><br>

Syntax:

 DC_DbStruct ( [<nMode>] ) -> aStructure

Returns:

 A Multi-dimensional array.

Arguments:

<nMode> is used to select the style of structure to be returned:

 <nMode>      Description
 ---------- ------------------------------------------------
  0 DEFAULT  Returns four (4) parallel sub-arrays rather than
             ragged arrays.

  1          Returns a ragged array similar to dbStruct()
             except each sub-array consists of 7 elements
             instead of 4 elements:

             Element   Type  Description
             -------  ------ -------------------------------
                1        C    Field Name
                2        C    Field Type
                3        N    Field Length
                4        N    Field Decimals
                5        C    Field Name
                6        C    Field Type
                7        X    Default value (the value in the
                              field of the current record)

Examples:

 -- Example 1 --

 // use a Database
 . use express via foxcdx

 // save the structure
 aStru := DC_DBSTRUCT(0)

 // create a .DBF of the same structure
 dc_dbcreate( 'express2.dbf', ;
              aStru[1], aStru[2], aStru[3], aStru[4] )

 -- Example 2 --

 // use a Database with a new structure
 . use newdata

 // save the structure
 . aStru := DC_DBSTRUCT(1)

 // close the database
 . CLOSE

 // use the Database with structure to be updated from new
 // structure
 . use olddata

 // update the structure with new fields and default data
 . DC_StruUpdate( aStru,, .t. )

Files:

_DCAREA.PRG, DCLIP1.DLL

See Also:

   dc_dbcreate()
   dc_struupdate()
   dc_isstru()


dc_dbstruw()

Display the structure of the selected database (wide format)

DC_DbStruW() is used to display the structure of the selected database file in a Wide format. A GUI dialog window displays the structure in a scrollable window with three columns of fields.

Syntax:

 DC_DbStruW() -> cFieldName

Returns:

 The name of the field selected by the user, a character string.

Arguments:

 None.

Examples:

 . USE COLLECT
 . DC_DbStruW()

Files:

_DCDBSTR.PRG, DCLIP1.DLL

See Also:

   DISPLAY STRUCTURE
   dc_dbstru()


dc_dbu()

A Gui Database Management Utility

DC_Dbu() is a database management utility that can be used to edit databases using any DBE including ADSDBE and ODBCDBE. DC_Dbu() is an MDI-based dialog that contains a status window at the top of the dialog. This status window displays information about the currently selected work area and also contain some pushbuttons to popup further status windows.<br><br>A menu at the top of the dialog provides a complete set of database utilities, searching features and printing features. It also allows for an MDI child browse/edit window to be created for each open work area. When a browse/edit window is given focus with the mouse, the work area of that window is selected and the status of the selected work area is displayed at the top of the dialog window.<br><br>All MDI child windows are opened in the same thread as the parent window. <br><br>

Syntax:

DC_Dbu( [<cParm1>],... [<cParm15>] ) -> nil.

Arguments:

<cParm1> thru <cParm15> may be any of the following arguments:

/an - Load ADSDBE driver (.NTX/.DBT support)
/ac - Load ADSDBE driver (.CDX/.IDX/.FPT support)
/dbe:<default dbe name>
/tbl:<database name>
/ind:<index list (separated by commas)
/odbc - Load ODBC driver
/dsn:<data source name> - ODBC (use a + for each space in name)
/uid:<user id> - ODBC
/pwd:<password> - ODBC
/dbq:<database name> - ODBC
/dll:<dllname> - Load a dynamic link library
/srv:<server name or drive letter> - ADSDBE
/obj:<objfilename> - Load an .OBJ file
/proc:<procedure> - Run a procedure ( with parameters)

Examples:

DC_Dbu('/odbc','/dsn:dBASE Files','/adsntx','/obj:TEST.OBJ', ;
       '/proc:MyMenu()' )

Files:

_DCDBU.PRG,DCLIP1.DLL

See Also:

   dc_dot()
   dbu


dc_debugbrowse()

Send debug information to a browse-style debugging window

DC_DebugBrowse() is used to send data to a browse-style debugging window when debugging GUI applications. <br><br> A list of expressions may be included and the output of each expression will be displayed in a new row in the browse window.<br><br> This is a major improvement over DC_DebugQout() because it uses an array browse rather than a memo to show debug information. Improvements: a. Updating the window is much faster therefore does not slow down application.<br><br> b. Data is in resizeable and moveable columns<br><br> c. Each debug line may have its own color.<br><br> d. Supports multiple windows.<br><br> e. Double-Clicking on debug item in window displays more info about that item, such as array browsing, object inspecting, etc.<br><br> f. Information doesn't scroll off the window. No limit to amount of debugging information.<br><br><br><br> <br><br>

Syntax:

DC_DebugBrowse ( { <xExpr1,...xExprN>}, ;
                 [<aExprTitle>], ;
                 [<nWindow>], ;
                 [<nbFgColor>], ;
                 [<nBgColor>], ;
                 [<lbPause>] ) -> NIL

Arguments:

<xExpr1> through <xExprN> is any expression.
The return value of each expression will be displayed in column
1 of the browse.

<aExprTitle> is an optional array of character strings to display
in column 2 of the browse.  There should be 1 item for each exprX
item.  These may be used as descriptors of the data being displayed.

<nWindow> is the debug window to send the information.
If this clause is not used then the information is sent to debug
window # 1.

<nbFgColor> and <nBgColor> are the foreground and background
colors of the information to display in the window.  If <nbFgColor>
is a code block, then <nBgColor> is ignored.  The code block must
return an array of two numeric elements, ie a foreground color
and a background color.

<lbPause> may be a logical variable or a code block.  If <lbPause>
is a logical .TRUE. then the program execution will be stopped until
the "Continue" button on the debug window is activated.  If <lbPause>
is a codeblock then the program execution will be stopped if the
codeblock returns a .TRUE. when evaluated.

Notes:

DC_DebugQoutAppendBlock() is a get-set function used to setupadditional information to append to each debug line.

Examples:

 #include "dcdialog.ch"

 USE COLLECT NEW SHARED

 DC_DebugBrowse( { Alias(), RecNo(), {'Alias','Record #'}, ;
                 2, {||IIF(RecNo()==3,;
                        {GRA_CLR_RED,GRA_CLR_WHITE}
                        {GRA_CLR_BLACK,GRA_CLR_WHITE})} )

 DC_DebugBrowse( { SetAppWindow() } )

 DC_DebugBrowse( { Directory() } )

Files:

_DCQOUT.PRG, DCLIPX.DLL

See Also:

   DCBDEBUG


dc_debugbrowseenable()

Enable debugging with an environment variable

DC_DebugBrowseEnable() is used to disable all DCBDEBUG commands unless a specified environment variable exists.

Syntax:

DC_DebugBrowseEnable ( <aEnvirVars> ) -> nil

Returns:

Nil.

Arguments:

<aEnvirVars> is an array of character strings which are the names
of environment variables to test.  If any of the environment
variables contains a YES, ON, HO or JA, then DCBDEBUG commands
will be enabled, otherwise they will be disabled.

Examples:

 IF lRunningAsService
   // No environment variable named ABCDEFGHI exists, so disable debug
   DC_DebugBrowseEnable( {"ABCDEFGHI"} )
 ELSE
   // Disable debug if there is no env var named DEBUG=YES
   DC_DebugBrowseEnable( {"DEBUG"} )
 ENDIF

Files:

_DCQOUT.PRG, DCLIPX.DLL

See Also:

   DCBDEBUG
   dc_debugbrowse()


dc_debuglogfile()

Set the name of the Debug Log file.

DC_DebugLogFile() is a Get-Set function that is used to set the name of the log file when using the DC_DebugLog() function or DCLDEBUG* commands.

Syntax:

DC_DebugLogFile( [<cFileName>] ) -> cOldFileName

Returns:

A character string.

Arguments:

<cFileName> is the name of the log file.

Examples:

DC_DebugLogFile('E:\temp\debug.log')

DCLDEBUG Date(), Time()

Files:

_DCQOUT.PRG

See Also:

   DCLDEBUG


dc_debuglogout()

Send debug information to a debugging log file

DC_DebugLogOut() is used to send data to a log file when debugging GUI applications. <br><br> A list of expressions may be included and the output of each expression will be displayed on a new line in the file.<br><br> <br><br>

Syntax:

 DC_DebugLogOut( <xExpr1> ) -> NIL

Arguments:

<xExpr1> through <xExprN> is any expression.

Notes:

DC_DebugQoutAppendBlock() is a get-set function used to setupadditional information to append to each debug line.

Examples:

 #include "dcdialog.ch"

 USE COLLECT NEW SHARED

 DC_DebugLogOut( { Alias(), IndexOrd() } )

Files:

DCDIALOG.CH

See Also:

   DCQDEBUG
   DCLDEBUG


dc_debugqout()

Send debug information to a debugging window

DC_DebugQout() is used to send data to a debugging window when debugging GUI applications. <br><br> A list of expressions may be included and the output of each expression will be displayed on a new line in the window.<br><br> <br><br>

Syntax:

 DC_DebugQout( {<xExpr1>,...<xExprN>} ) -> NIL

Arguments:

<xExpr1> through <xExprN> is any expression.

Notes:

DC_DebugQoutAppendBlock() is a get-set function used to setupadditional information to append to each debug line.

Examples:

 #include "dcdialog.ch"

 USE COLLECT NEW SHARED

 DC_DebugQout( { Alias(), IndexOrd() } )

Files:

DCDIALOG.CH

See Also:

   DCQDEBUG
   dc_debugqoutappendblock()
   dc_qout()
   DCQOUT


dc_debugqoutappendblock()

Post a codeblock for information to append to debug window

DC_DebugQoutAppendBlock() is a get-set function used to setup additional information to append to each debug line.<br><br>The default code block returns the call stack.<br><br>{||' <- Called From: ' + ; ProcName(2) + '('+Alltrim(Str(ProcLine(2)))+'), ' + ; ProcName(3) + '('+Alltrim(Str(ProcLine(3)))+'), ' + ; ProcName(4) + '('+Alltrim(Str(ProcLine(4)))+')' }<br><br> <br><br>

Syntax:

 DC_DebugQoutAppendBlock( <bExpr> ) -> bOldExpr

Returns:

A Code Block.

Arguments:

<bExpr> is a code block that returns a character string.

Examples:

 #include "dcdialog.ch"

 DC_DebugQoutAppendBlock( {||' <- Called From: ' + ;
   ProcName(2) + '('+Alltrim(Str(ProcLine(2)))+')' }

 USE COLLECT NEW SHARED

 DC_DebugQout( { Alias(), IndexOrd() } )

Files:

DCDIALOG.CH

See Also:

   DCQDEBUG
   dc_debugqout()
   dc_qout()
   DCQOUT


dc_debugwindowbrowsefont()

Sets font for the debug window

DC_DebugWindowBrowseFont() is a Get-Set function that is used to set the font for the debug window created by the WTF command.

Files:

_DCQOUT.PRG, DCLIPX.DLL

See Also:

   WTF
   dc_debugbrowse()


dc_dec2hex()

Returns a hexidecimal number from a numeric value

DC_DEC2HEX() will convert a numeric value to Hexidecimal.<br><br><br><br>

Syntax:

DC_Dec2Hex( <nDecimal> ) -> cHexidecimal

Returns:

 A character string.  Example: 5D

Arguments:

<nDecimal> is a numeric value from 0 to 255.

Files:

_DCAND.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_bittest()
   dc_andbits()


dc_dec2longint()

Converts Long Integer (32 bits) to binary character

DC_Dec2LongInt() converts a Long Integer (32 bits) TO binary character representation<br><br><br><br>

Syntax:

DC_Dec2LongInt( <nDecimal> ) -> cBinaryString

Returns:

 A character string that is the binary equivalent of the passed
 argument (32 characters).

Arguments:

<nDecimal> is a numeric value from 0 to 4294967295.

Files:

_DCFUNCT.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_dec2hex()
   dc_xorbitslong()


dc_delete()

Mark record(s) for deletion

DC_Delete() is used to mark records for deletion based on a set of conditions. A GUI dialog is displayed for the user to select the conditions.

Syntax:

 DC_Delete() -> lStatus

Returns:

 A logical .TRUE. if records were deleted successfully, .FALSE.
 otherwise.

Arguments:

 None.

Examples:

 . USE EXPRESS INDEX EXPRESS.CDX SHARED
 . DC_Delete()

Files:

_DCDELE.PRG, DCLIP1.DLL

See Also:

   DELETE
   dc_recall()


dc_dimscreen()

Dim and disable a screen or the entire desktop.

DC_DimScreen() will dim and disable a gui screen or the entire desktop. Use this function fo force the user to focus on a new window or process.<br><br>This function creates a new window with a DCSTATIC child object to overlay the target screen. The new window is set to a specified color and transparency to give the illusion that the target screen is being changed, but it is only being overlayed.

Syntax:

DC_DimScreen( <oDialog>, ;
              [<nColor>], ;
              [<nTransparency>], ;
              [<bGets>] ) -> <oDialog2>

Returns:

A pointer to the overlaying window.
This window must be destroyed with the :destroy() method.

Arguments:

<oDialog> is the dialog window to dim.  To dim the entire
desktop, this should be AppDeskTop().

<nColor> is the color to use for the dimming. Default is
GRA_CLR_BLACK.

<nTransparency> is the amount of transparency to use.
Default is 50.

<bGets> is a code block to evaluate that will add items
to the overlaying static.  The code block will receive 2
parameters: (1) The Getlist array, (2) the Static object.

Examples:

See the sample program in .\samples\dimmer\dimmer.prg.

Files:

_DCFUNCT.PRG


dc_dir()

Display a directory of files or databases

DC_Dir() is used to display a directory of files or databases.

Syntax:

 DC_Dir( [<cFileSpec>] ) -> lStatus

Returns:

 A logical .TRUE. if any files were displayed, .FALSE. otherwise.

Arguments:

<cFileSpec> is the specification of the files to display including
path and extension.  The file dialog shows the file name, date,
size and time.

If no argument is passed, then only .DBF database files will be
displayed.  This dialog allows for the file to be automatically
opened when the item is selected.  The database dialog shows the
file name, date, size, number of records, and type of database.

Examples:

 . DC_Dir()   // display all database files
 . DC_Dir('*.TXT') // display all text files

Files:

_DCDIR.PRG, DCLIP1.DLL

See Also:


dc_dispbegin()

Begin buffering screen output

Clipper's DISPBEGIN() and DISPEND() functions will not behave properly if they are not nested properly, i.e. the same number of DISPBEGIN() calls and DISPEND() calls. DC_DISPBEGIN() and DC_DISPEND() are simply front-end calls to the associated Clipper functions that keep a static counter ensuring that DC_DISPCLEAR() can properly clear out the buffers in the error handler.

Syntax:

DC_DispBegin () -> nil

Returns:

 nil

Arguments:

 None

Notes:

Use DC_DISPBEGIN() and DC_DISPEND() in place of Clipper's DISPBEGIN() and DISPEND() when using DC_DISPCLEAR() to clear the display buffers.

Examples:

 See Clipper 5.x Guides DISPBEGIN(), DISPEND()

Files:

_DCDISP.PRG/.OBJ, DCLIPX.LIB


dc_dispclear()

Clear the screen output buffers

DC_DISPCLEAR() is used in your error handler to clear the display buffers during an error. This function is needed only if you use Clipper's DISPBEGIN() and DISPEND() in your application.<br><br> Clipper's DISPBEGIN() and DISPEND() functions will not behave properly if they are not nested properly, i.e. the same number of DISPBEGIN() calls and DISPEND() calls. DC_DISPBEGIN() and DC_DISPEND() are simply front-end calls to the associated Clipper functions that keep a static counter ensuring that DC_DISPCLEAR() can properly clear out the buffers in the error handler.

Syntax:

DC_DispClear () -> nil

Returns:

 Nil

Arguments:

 None

Notes:

Use DC_DISPBEGIN() and DC_DISPEND() in place of Clipper's DISPBEGIN() and DISPEND() when using DC_DISPCLEAR() to clear the display buffers.

Examples:

 See Clipper 5.x Guides DISPBEGIN(), DISPEND()

Files:

_DCDISP.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_dispbegin()
   dc_dispend()


dc_dispend()

End buffering screen output

Clipper's DISPBEGIN() and DISPEND() functions will not behave properly if they are not nested properly, i.e. the same number of DISPBEGIN() calls and DISPEND() calls. DC_DISPBEGIN() and DC_DISPEND() are simply front-end calls to the associated Clipper functions that keep a static counter ensuring that DC_DISPCLEAR() can properly clear out the buffers in the error handler.

Syntax:

DC_DispEnd () -> nil

Returns:

 Nil

Arguments:

 None

Notes:

Use DC_DISPBEGIN() and DC_DISPEND() in place of Clipper's DISPBEGIN() and DISPEND() when using DC_DISPCLEAR() to clear the display buffers.

Examples:

 See Clipper 5.x Guides DISPBEGIN(), DISPEND()

Files:

_DCDISP.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_dispbegin()


dc_dispmem()

Display the contents of a memory file or current memory

DC_DispMem() is used to display the contents of an .XPF (memory) file or the current contents of memory (PUBLICS/PRIVATES only) in a GUI scrolling browse window.

Syntax:

 DC_DispMem( [<cMemFileName>] ) -> lStatus

Returns:

 A logical .TRUE. if successful.

Arguments:

<cMemFileName> is the name of the memory file.  If no extension
is given then .XPF is assumed.

If no argument is passed then the current contents of memory
are saved to a file named EXPRESS.XPF and the contents of
EXPRESS.XPF are displayed.  NOTE: If any PUBLIC or PRIVATE
memory variables exist containing non-persistent data such as
objects or some type of code blocks, a runtime error will
result and the contents of memory cannot be displayed.

Examples:

 . custname := 'Donnay Software'
 . product := 'eXPress++ 2.0'
 . DC_DispMem()
 . DC_DispMem('PRODUCT.XPF')

Files:

_DCMEM.PRG, DCLIP2.DLL

See Also:

   dc_xpftoarray()


dc_dlllist()

List all loaded dynamic .DLLs

DC_DllList() is used to list all the dynamic .DLLs that are currently loaded. These .DLLs must have been loaded with DC_DllLoad() or DLL LOAD.

Syntax:

 DC_DllList() -> nil

Returns:

 Nil.

Arguments:

<cDllName> is the name of the .DLL to load.  If this argument
is not passed a GUI dialog will be displayed prompting for the
name.

<lMessage> if .TRUE. (default) will display a GUI message box
if the .DLL could not be loaded.

Examples:

 . DC_DllLoad('MYTEST')
 . DC_DllLoad('MYFUNCS')
 . DC_DllList()

Files:

_DCDLL.PRG, DCLIP1.DLL

See Also:


dc_dllload()

Load a dynamic .DLL

DC_DllLoad() is used to load a dynamic .DLL and save away information about the .DLL in a static array to be used later with DC_DllUnload().

Syntax:

DC_DllLoad( [<cDllName>], ;
            [<lMessage>] ) -> lStatus

Returns:

 A logical .TRUE. if the .DLL was successfully loaded, .FALSE.
 otherwise.

Arguments:

<cDllName> is the name of the .DLL to load.  If this argument
is not passed a GUI dialog will be displayed prompting for the
name.

<lMessage> if .TRUE. (default) will display a GUI message box
if the .DLL could not be loaded.

Examples:

 . DC_DllLoad('MYTEST')
 . DO test
 . DC_DllUnload('MYTEST')

Files:

_DCDLL.PRG, DCLIP1.DLL

See Also:

   DLL LOAD
   dc_dllunload()
   dc_dlllist()


dc_dllunload()

UnLoad a dynamic .DLL

DC_DllUnload() is used to unload a dynamic .DLL that was previously loaded with DLL LOAD or DC_DllLoad().

Syntax:

DC_DllUnload( <cDllName> ) -> lStatus

Returns:

 A logical .TRUE. if the .DLL was successfully unloaded.

Arguments:

<cDllName> is the name of the .DLL to unload.

Examples:

 . DC_DllLoad( 'MYTEST' )
 . DO test
 . DC_DllUnload( 'MYTEST' )

Files:

_DCDLL.PRG, DCLIP1.DLL

See Also:

   dc_dllload()
   DLL UNLOAD


dc_do()

A handy method of creating a late-binding call to a function

DC_DO() is used to run any program or function. DC_DO() is used in place of DO <proc> or <function> in applications where the developer wishes to control which procedures or functions get linked into an application by simple EXTERNAL tables.<br><br> DC_DO() runs procedures or functions, but does not force the linker to link them into the .EXE program. For example, the command: DO ACCTSPAY in an application would always force the module or object ACCTSPAY to be linked into the .EXE by your linker. If however, you replace DO ACCTSPAY with DC_DO('ACCTSPAY'), then the ACCTSPAY module will only be linked in to the .EXE with an EXTERNAL ACCTSPAY command or by the dCLIP "dynamic-linker". DC_DO() should be used when calling procedures or functions which are in dynamic libraries (.DLBs).<br><br> With DC_DO() the developer can create an application with many OPTIONS yet use common source code. The options for a specific customer or product configuration can be controlled through EXTERNAL tables.

Syntax:

DC_Do ( <cProgToDo>, ;
        [<cProgToCall>] ) -> xValue

Returns:

 The value returned by the function called.

Arguments:

<cProgToDo> is the name of the procedure or function to execute
in "quotes".

<cProgToCall> is the name of any additional procedure or
function to execute in the event that DC_DO() cannot find
procedure <cProgToDo> in the .EXE or in a dynamic library.

Examples:

 . ? DC_DO( "dc_assist()" )

Files:

_DCDO.PRG/.OBJ, DCLIPX.LIB

See Also:


dc_docase()

Evaluate a list of expressions based on a CASE condition

DC_DOCASE() is a "function" replacement for DO CASE...ENDCASE when a function is needed, i.e. for calling via macro, code blocks, etc.<br><br>

Syntax:

DC_DoCase ( <aCase>, ;
            <aEval> ) -> Nil

Returns:

 Nil.

Arguments:

<aCase> is an array of code blocks to evaluate.

<aEval> is an array of code blocks to execute.  The first code
block in array <aCase> that evaluates true will force the
corresponding code block in the parallel array <aeval> to be
evaluated.

Notes:

Only one (1) code block in the <aEval> array will be evaluated.

Examples:

 aCase := { { || lastkey()=27 }, { || lastkey()=13 } }
 aEval := { { || abort() }, { || accept() } }

 inkey(0)
 DC_DOCASE(  aCase, aEval )

Files:

_DCEVAL.PRG, DCLIP1.DLL

See Also:

   dc_ifelse()
   dc_dowhile()


dc_dot()

A Dot-Prompt Interpreter

DC_Dot() is a dot-prompt interpreter that is used to execute any Xbase++ command, eXPress++ command or User-Defined command. DC_Dot() will open a new Dialog Window and allow the user to enter and interpret commands.<br><br>The standard eXPress++ command set is DCSTD.CH. This file must exist in your INCLUDE path or no commands can be interpreted. When DCSTD.CH is loaded, it also loads the most common Xbase++ include files like STD.CH, INKEY.CH, etc, the dialog command set, DCDIALOG.CH and file named DCCUSTOM.CH.<br><br>DCCUSTOM.CH is where all custom user-defined commands are entered, including references to other .CH files, thus allowing virtually an unlimited command set.<br><br>Commands entered at the dot-prompt may reference any manifest constant that has also been defined in one of the files that are part of the INCLUDE set.<br><br>To return from DC_Dot() type EXIT at the dot-prompt.<br><br>To quit the application type QUIT at the dot-prompt.<br><br>DC_Dot() is an interpreter which provides similar functionality to the dBASE/FoxPro/dCLIP dot-prompt. The heart of the interpreter is the runtime pre-processor and the DCSTD.CH/STD.CH command sets.<br><br>If you grew up with dBASE-II or dBASE-III and graduated to Clipper, you will find yourself in familiar territory when you use DC_Dot(). The dot prompt is similar to the dBASE interactive programming environment that allows any of the built-in command set to be invoked from the dot prompt. DC_Dot() is slightly different however, because it combines the best of 3 worlds. This "integration" of a pre-processor, intepreter, compiler and robust library allows unsurpassed speed and compatability in accomplishing Xbase++/eXPress++ development tasks.<br><br>When a command is entered at the dot-prompt, it's first passed through the Xbase++ pre-processor to convert it to a set of expressions. The expression list is then "macro-compiled" and evaluated.<br><br>The eXpress++ dot prompt is fully-interactive, meaning that you get an instant response to the command at the moment you enter it from the keyboard.<br><br>EXAMPLE:<br><br> Assume that your client wants to get a quick average of all sales within a specified date period. Then he wants to replace the sales representative for all his CALIFORNIA customers. If you did not accomodate this capability in your executable program, your client is out of luck or must accomplish the task without the aid of your program. With the DC_DOT() function linked into your program, this task can be accomplished in seconds by entering the following commands at the dot:<br><br> . USE \ACCTSPAY\CUSTOMER VIA FOXCDX . AVER SALES TO TOTSALES FOR SHIPDATE > DATE()-30 . ? TOTSALES 12677.52 . REPL SALESREP WITH 'JONES' FOR STATE='CA'<br><br>If you like working from a command-line, then the DOT is the starting place or "home" for just about everything you need to do in an Integrated Development Environment. You can run any other executable program (regardless of size), run any DOS command, run any Xbase++ or user-defined command, evaluate any Xbase++ expression, execute any batch file, edit source files, even compile and run object code without ever leaving the interactive environment of the dot prompt. When you run an application program, you will return to the DOT. When you run another executable program such as your own editor, word- processor, spread-sheet, calendar, etc. you will return to the DOT. When you compile your source code, you will return to the DOT.<br><br>The dot-prompt is also a medium for experimenting with commands, functions, classes and language elements by allowing the user or programmer to create memory variables, arrays or objects "on-the-fly".<br><br><br><br>

Syntax:

 DC_Dot( [<lModal>], ;
         [<nTimerRefresh>] ) -> NIL

Arguments:

<lModal> runs the Dot-Prompt in "Psuedo-Modal" mode. It is not
actually modal but instead disables the SetAppWindow().  When
the EXIT button is pressed or the EXIT command is entered at the
dot-prompt, the user is given the option of closing the window
or exiting and returning control to the calling program.

<nTimerRefresh> is the refresh interval, in 1/100 of a second,
to refresh the status area at the top of the window.

Examples:

/* -- Example 1 Calling the dot-prompt from in-line code -- */

IF lDebugOn
  DC_Dot()
ENDIF

/* -- Example 2 Calling the dot-prompt from a Hot-Key -- */

SET KEY K_ALT_D TO DC_DOT
@ 1,1 SAY 'Enter Name' GET cName
READ
SET KEY K_ALT_D TO nil

/* -- Example 3 Calling the dot-prompt from eXPress++ dialog -- */

DCHOTKEY xbeK_ALT_D ACTION {||DC_Dot(.f.)}
DCREAD GUI FIT ADDBUTTONS

Files:

_DCDOT.PRG,DCLIP1.DLL

See Also:

   dc_interpret()
   dc_dotsize()


dc_dotdoskey()

Set DC_Dot() command stack operation to Dos-Key emulation

DC_DOTDOSKEY() is used to set the behavior of the dot-prompt command stack navigator to emulate that of DOS command stack navigators like Dos-Key or OS/2.<br><br> The normal behavior allows commands to be reissued in sequence and expedite processes that are used again and again. Dos-Key emulation automatically copies the selected command to the bottom of the stack after execution and creates a blank command line for input.<br><br><br><br>

Syntax:

DC_DotDosKey ( <lMode> ) -> nSize

Returns:

 A logical value equivalent to the last setting of the value.

Arguments:

<lMode> if .TRUE. will set the Dos-Key emulation on.  If
.FALSE. the command stack operation will be restored to
the normal (default) operation.

Files:

_DCDOT.PRG

See Also:

   dc_dot()


dc_dothotkey()

Set the Dot-Prompt hot key

DC_DOTHOTKEY() is used to establish the hot key to use to call up the dot prompt when in the GUI reader or in the standard event loop function: DC_ReadGuiEventLoop(). The default key is ALT-D.<br><br> If the DCLIP1.DLL and DCLIP2.DLL libraries (eXPress++ 2.0) are statically linked to your application using DCLIP1.LIB and DCLIP2.LIB then the DC_Dot() function will be called directly, otherwise an attempt will be made to dynamically load DCLIP1.DLL and DCLIP2.DLL before calling DC_Dot().<br><br>

Syntax:

DC_DotHotKey ( [<nHotKey>] ) -> nOldHotKey

Returns:

 A numeric value.

Arguments:

<nHotKey> is any keyboard key defined in APPEVENT.CH.

Examples:

 DC_DotHotKey(xbeK_F12)

Files:

_DCGETBX.PRG

See Also:

   dc_readguieventloop()


dc_dotsize()

Set the size of the Dot-Prompt command stack

DC_DOTSIZE() is used to increase the length of the Dot-Prompt command stack array to a value greater than the default value of 100 commands. This is desirable in the event that it is necessary to save and restore more than the last 100 commands with the HISTORY=<file> command in your DCLIP.SYS.<br><br>

Syntax:

DC_DotSize ( [<nSize>] ) -> nSize

Returns:

 A numeric value equal to the previous setting of the command
 stack size.

Arguments:

<nSize> is a number from 100 to 4000

Examples:

DC_DOTSIZE(500)

Files:

_DCDOT.PRG

See Also:

   dc_dot()


dc_dotvar()

Returns a pointer to an array of passed info to DC_Dot()

DC_DotVar() returns an array of info about the dialog window and Getlist for the dialog that invokes the dot-prompt when using DC_DotHotKey().<br><br>

Syntax:

DC_DotVar() -> aArray

Returns:

An array of 3 elements:

1. A pointer to the DC_XbpDialog1() object.
2. A pointer to the GetList array.
3. A pointer to the DC_GetList() object.

Files:

_DCGETBX.PRG, DCLIPX.DLL

See Also:

   dc_dothotkey()
   dc_dot()


dc_dowhile()

Evaluate a list of expressions based on a CASE condition

DC_DOWHILE() is a "function" replacement for DO WHILE..ENDDO loops to be used when a function is needed, i.e. for calling via macro, code blocks, etc.<br><br><br><br>

Syntax:

 DC_DoWhile ( <bWhile>, ;
              <bEval> ) -> nil

Returns:

 Nil.

Arguments:

<bWhile> is a code-block to evaluate in each iteration of the
WHILE loop.  The loop will be terminated when <bWhile>
evaluates .FALSE. or when the ESCape key is pressed.

<bEval> is a code-block to evaluate in each iteration of the
WHILE loop.

Examples:

 bWhile := { || !EOF() }
 bEval := { || dbskip(1), qout( recno(), &(field(1)) ) }
 setkey( -1, { || DC_DOWHILE( bWhile, bEval } )

Files:

_DCEVAL.PRG, DCLIP1.DLL

See Also:

   dc_ifelse()
   dc_docase()


dc_drag()

Drag window coordinates and return a coordinate array

DC_DRAG() is used to designate an area of the screen you want to use by giving the operator a box to drag around with the cursor keys or the mouse. After the operator has chosen the screen coordinates, pressing the <enter> key or releasing the mouse button will return the 4 coordinates in an array.<br><br> During the dragging process if the drag was not invoked by the mouse, then the TAB key will switch between the 9 dragging modes.

Syntax:

DC_Drag ( <nStRow>, ;
          <nStCol>, ;
          <nEnRow>, ;
          <nEnCol>, ;
          <nDragMode>, ;
          [<nMinWidth>],
          [<nMinHeight>] ) -> aCoordinates

Returns:

 An array of four (4) elements with the coordinates selected by
 the user.

Arguments:

<nStRow>, <nStCol>, <nEnRow>, <nEnCol> are the screen
coordinates that you want to start the drag or window sizing
from.   If no coordinates are passed then the dragging will
start from the extreme coordinates of the display.

<nDragMode>  :  DRAG_UPPER_LEFT    1
                DRAG_UPPER_RIGHT   2
                DRAG_LOWER_LEFT    3
                DRAG_LOWER_RIGHT   4
                DRAG_LEFT          5
                DRAG_RIGHT         6
                DRAG_UPPER         7
                DRAG_LOWER         8
                DRAG_ENTIRE_BOX    9

<nMinWidth> is the minimum width of the new box.

<nMinHeight> is the minimum height of the new box.

Examples:

 // get a set of screen coordinates from the operator.
 aCoord := DC_DRAG( aCoord )

 // Explode a window to the passed coordinates.
 DC_EXPL( aCoord[1], aCoord[2], aCoord[3], aCoord[4] )

Files:

_DCDRAG.PRG/.OBJ, DCLIPX.LIB


dc_drive2unc()

Returns a UNC from a mapped drive letter

DC_Drive2UNC() returns the UNC from a mapped drive letter.<br><br>

Syntax:

DC_Drive2UNC( <cDrive> ) -> cUNC

Returns:

A Character String.

Arguments:

<cDrive> is the drive letter.

Files:

_dcfunct.prg, dclipx.lib, dclipx.dll

See Also:

   dc_unc2drive()


dc_editconfig()

Edit a source file

DC_EDITCONFIG() is used to configure the name of your editor. Functions like DC_CallStack() and DC_EditPrg() will call your editor if it has been properly configured. When the dot prompt is called for the first time in a program or a call to DC_Init() is made, a file named DCLIP.SYS is read to configure the environment. An EDITOR=<editor file name> statement in DCLIP.SYS will pass the <editor file name> to DC_EditConfig() to set up your default editor.<br><br>

Syntax:

 DC_EditConfig( [<cEditorFileName>] ) -> cEditorFileName

Returns:

 The name of the editor previously stored in memory.

Arguments:

<cEditorFileName> is the full-path file name of your editor
or the name of a .BAT file that calls your editor.  This
file name is passed the name of the file to edit and the line
number.

Notes:

If the drive and directory is not included in the <cFileName> argument, then DC_EDITPRG() will search for the file first in the SET DCLIP directory followed by the SET PDIR directory (if file is a .PRG).

Examples:

 . DC_EDITCONFIG( 'C:\mew\mew.bat' )
 . DC_EDITPRG( 'test' )

 Contents of me.bat (used to call Multi-Edit for Windows):

 @ECHO OFF
 @IF '%2'=='' C:\mew\mew32 %1
 @IF NOT '%2'=='' C:\mew\mew32 %1 /l%2

Files:

_DCEDPRG.PRG, DCLIP1.DLL

See Also:

   dc_editprg()
   dc_callstack()


dc_editcontrollastfocus()

Returns last edit control that had focus

DC_EditControlLastFocus(). will return a pointer to the last edit control that had focus. Handy for returning to a Get after hitting a hot key or clicking a pushbutton.<br><br>

Syntax:

DC_EditControlLastFocus() -> oLastFocus

Returns:

An object.

Arguments:

None

Files:

_DCGETBX.PRG, DCLIPX.DLL


dc_editprg()

Edit a source file

DC_EDITPRG() is used to edit a source code file. This function will use the editor defined as the "system" editor via the EDITOR= command in DCLIP.SYS or the DC_EDITCONFIG() function.<br><br> If no external editor is defined, then an imbedded GUI text editor will be used.<br><br>

Syntax:

 DC_EditPrg( <cFileName>, ;
            [<nLineNmbr>], ;
            [<cParameters>] -> lStatus

Returns:

 A logical .TRUE. if editor was called successfully.

Arguments:

<cFileName> is the name of the ascii file to edit.  If no
argument is given, then the user will be prompted for the name
of the file. If no extension is included, then .PRG is
assumed.

<nLineNmbr> is the line number to go to.  If no parameter is
passed then the editing will start at line 1.

<cParameters> is an optional set of parameters to pass to the
editor.

Notes:

If the drive and directory is not included in the <cFileName> argument, then DC_EDITPRG() will search for the file first in the SET DCLIP directory followed by the SET PDIR directory (if file is a .PRG).

Examples:

 . dc_editconfig( 'ME.BAT' )
 . DC_EDITPRG( 'test' )

Files:

_DCEDPRG.PRG, DCLIP1.DLL

See Also:


dc_enabletabpagecolors()

Get-Set function for enabling/disabling tab page colors

DC_EnableTabPageColors() is a Get-Set function that is used to enable or disable the painting of Tabpage colors when tabpages are created with the @ DCTABPAGE command.<br><br>By default, tab page colors are always enabled.<br><br>All tabpage colors may be disabled throughout the application by call DC_EnableTabPageColors(.F.). This would be desirable when using the CodeJock SkinFramework system when tab colors from the skin are preferable.<br><br>

Syntax:

DC_EnableTabPageColors( <lEnable> ) -> lOldEnable

Arguments:

<lEnable> if .TRUE. will enable tab page colors (default).  If
.FALSE. will disable tab page colors.

Files:

_dcclass.prg, dclipx.dll

See Also:

   @ DCTABPAGE


dc_enterexitmode()

Get/Set behavior of ENTEREXIT clause

DC_EnterExitMode() is a Get/Set function used to establish the behavior of the ENTEREXIT clause of DCREAD GUI.<br><br>

Syntax:

DC_EnterExitMode( [<nMode>] ) -> nOldMode

Returns:

A numeric value.

Arguments:

<nMode> sets the new mode in accordance with the below table.

* - Default

<nMode>   Description
-------  -----------------------------------------------------
  0  *    Standard Enter-Exit (exits if ENTER is pressed on last Get)
  1       ENTER pressed on last Get gives focus to OK button.
  2       Exits if ENTER is pressed any time.

Examples:

DC_EnterExitMode(1) // Pressing enter in last get gives focus to OK button.

Files:

_DCGETBX.PRG, DCLIPX.DLL

See Also:

   DCREAD GUI


dc_envirrest()

Restore the environment from an array or file

DC_ENVIRREST() is used to restore all 38 Clipper environment variables from an array or a file created by DC_ENVIRSAVE().<br><br> The Clipper environment consists of everything from SET CURSOR, SET DEFAULT, to SET ALTERNATE, etc.<br><br> Use this function to restore the Clipper environment after running a task that may have altered the environment.

Syntax:

DC_EnvirRestore ( <aEnvir> | <cEnvirFile> ) -> NIL

Returns:

 NIL

Arguments:

<aEnvir> is an array of environment variables that was saved by
DC_ENVIRSAVE().

<cEnvirSave> is an array file containing the contents of the
environment that was saved by DC_ENVIRSAVE( <cEnvirSave> ).

Examples:

 -- EXAMPLE 1 --

 aEnvir := dc_envirsave()
 do something
 DC_ENVIRREST( aEnvir )

 -- EXAMPLE 2 --

 dc_envirsave( 'ENVIR.AR' )
 do something
 DC_ENVIRREST( 'ENVIR.AR' )

Files:

_DCENVIR.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_envirsave()


dc_envirsave()

Save the entire environment to an array or file

DC_ENVIRSAVE() is used to save all 38 Clipper environment variables to an array or a file for later restoring by DC_ENVIRREST().<br><br> The Clipper environment consists of everything from SET CURSOR, SET DEFAULT, to SET ALTERNATE, etc.

Syntax:

DC_EnvirSave ( <cFileName> ) -> nil

Returns:

 The 38 Clipper environment variables in an array.  See ARRAY.CH
 (included in Clipper distribution) for the values.

Arguments:

<cFileName> the name of the file to save the Clipper
environment to.

If no argument is passed then no file will be created, however
the current Clipper environment will still be returned in an
array.

Examples:

 -- Example 1 --

 aEnvir := DC_ENVIRSAVE()
 do something
 dc_envirrest( aEnvir )

 -- Example 2 --

 DC_ENVIRSAVE( 'ENVIR.AR' )
 do something
 dc_envirrest( 'ENVIR.AR' )

Files:

_DCENVIR.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_envirrest()


dc_eof()

Is the record pointer at the end of the file?

DC_EOF() is used to test whether or not DC_DbSkip() attempted to move the record pointer past the bottom record in a "scoped" set of records when using a positive skip value. If no scope is set or the ADSDBE is being used as the data driver for the current work area this function simply calls Eof() therefore it can be used as a replacement for Eof().<br><br>

Syntax:

 DC_Eof() -> lStatus

Returns:

 A logical value.

Arguments:

 None.

Notes:

Examples:

 DC_SetScope(0,'12001')
 DC_SetScope(1,'12001')

 DC_DbGoTop()

 DO WHILE !DC_Eof()
   DC_DbSkip(1)
 ENDDO

Files:

_DCSCOPE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_setscope()
   dc_bof()
   dc_dbskip()
   dc_dbgotop()
   dc_dbgobottom()


dc_erase()

Delete a file

DC_Erase() is used to delete a file from the disk. A GUI user dialog is displayed to choose a file name to delete.<br><br>

Syntax:

 DC_Erase()

Returns:

 A logical .TRUE. if the file was successfully deleted, .FALSE.
 otherwise.

Arguments:

 None.

Examples:

 . DC_Erase()

Files:

_DCERASE.PRG, DCLIP1.DLL

See Also:


dc_error2string()

Converts an Error() object to a string

DC_Error2String() will generate a string of error information from the info in an Error() object.<br><br>The string will also contain stack info, environment info and status of all open workareas.

Files:

_DCFUNCT.PRG, DCLIPX.DLL


dc_errormsg()

Display an array of error messages in a window

DC_ERRORMSG() is used to display a popup error box onscreen. You can override the defaults for sound and title as optional params. The box is self centering onscreen; the text array is centered inside the box. Pressing any key or mouse button will remove the popup box.

Syntax:

DC_ErrorMsg ( <aMessage>, ;
              [<lSound>], ;
              [<cTitle>] ) -> nil

Returns:

 nil

Arguments:

<aMessage> is an array of messages to display in the popup
box.

<lSound> - if .FALSE. don't sound error beep; default is
.TRUE.

<cTitle> is the title displayed in top line center of popup
box; defaults to 'ERROR'

Notes:

dc_errormsg ( <aMessage>, [lSound], [cTitle] ) -> Nil

Examples:

 if !isprinter()
   DC_ERRORMSG( {'Printer Is Offline - Please Ensure Power',;
                 'Is On And Paper Is Inserted Properly'},;
                 '',;
                 ' Printer Error ')
 else
   ...
   ...
 endif

Files:

_DCMSG.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_msgbox()
   dc_alert()


dc_excel2array()

Create a 2-dimensional array from an Excel file

DC_Excel2Array() will create a 2-dimensional array from the contents of an Excel file.

Syntax:

DC_Excel2Array( <cFileName>, [<bEval>] ) -> aData

Returns:

A 2-dimensional array.

Arguments:

<cFileName> is the name of the Excel XLS file including the full
path.

<bEval> is a code block to evaluate after the Excel file is opened.
The Excel object and book automation object are passed to the code
block.  This can be used for formatting cells before the array is
created.

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_array2excel()
   dc_workarea2excel()
   dc_excel2workarea()


dc_expandtree()

Expand all nodes of a TreeView branch

DC_ExpandTree() will expand or collapse all sub branches of a specified tree branch in an XbpTreeView.

Syntax:

DC_ExpandTree( <oTreeItem> | <oTreeRoot>, ;
               [<lExpand>] ) -> nil

Returns:

Nil.

Arguments:

<oTreeItem> is any tree view branch object that is derived from
XbpTreeViewItem() or <oTreeRoot> is an object that is derived
from XbpTreeView().

If <lExpand> is .TRUE. (default) then the tree branch will be
expanded otherwise it will be collapsed.

Files:

_DCARRAY.PRG, DCLIPX.DLL


dc_expl()

Explode a Text or GUI dialogue window

DC_EXPL() is a Dual-Mode function that is used to explode a dialogue box on the screen. In TEXT mode, this function is a front-end to DC_EXPLODE() that uses pre-defined system colors which are part of the DCCOLOR color array. See DCCOLOR.CH for a definition of the color manifest constants. In GUI mode, it creates a GUI dialogue window. In both modes, it returns an array of information that is passed to compatible Dual-Mode functions like DC_Say(), DC_Cls(), and DC_Impl().<br><br> DC_EXPL() also stores the array of screen information in a static array so the functions DC_Say(), DC_Cls() and DC_Impl() can be called without passing the screen array.

Syntax:

DC_Expl( <nStartRow>, ;
         <nStartCol>, ;
         <nEndRow>, ;
         <nEndCol>, ;
         [<cTitle>], ;
         [<lNoShadow>], ;
         [<lPaintOnly>], ;
         [<lCenter>], ;
         [<lRelative>], ;
         [<cFont>], ;
         [<lGui>] ) -> aObject

Returns:

 An array of information about the screen object that is used
 with DC_Say(), DC_Cls() and DC_Impl().

Arguments:

<nStartRow>, <nStartCol>, <nEndRow>, <nEndCol> are the screen
coordinates, relative to 0,0 of the physical screen.

<cTitle> is the title heading on the top of the dialogue box.
If no argument is given, then there will be no title area.

<lNoShadow> if .TRUE. will prevent the shadow from being
created. Default is .FALSE. (shadow enabled).  This parameter
is used in TEXT mode only.

<lPaintOnly> if .TRUE. will paint the box on the screen but not
perform the "exploding" process.  Default is .FALSE. (explode).
This parameter is used in TEXT mode only.

<lCenter> will center the dialogue box on the screen and use
the coordinates only for determining the height and width
of the window.

<lRelative> if .TRUE. (default) assumes that coordinates
passed by DC_SAY() to this window are relative to location
0,0 of the window, otherwise they are relative to 0,0 of
the screen.

<cFont> is a valid font name for this window.  This font will
be used as the default for all Says in this window via DC_SAY().
If no font parameter is passed, the default it 10.Courier.
This parameter is used in GUI mode only.

<lGui> is used to override the setting of DC_GUI().  If <lGui>
is .TRUE. then this will be a GUI dialogue.  IF <lGui> is
.FALSE. it will be a TEXT dialogue, otherwise it will follow
the setting of DC_GUI().

Notes:

Use DC_EXPLMODE(.f.) to disable the exploding process when you want screens to display "instantly" instead of "explode".

This is particularly useful when running the application on a slower computer.

Use DC_ALTSHADOW(.t.) to display the shadow on the right side of the box.

Examples:

 -- Example 1 --

 aSaveScreen := DC_EXPL( 10,10,12,70, ' Enter a command ' )
 cCommand := SPACE(50)
 @ 11,12 get cCommand
 read
 dc_impl( aSaveScreen )

 -- Example 2 --

 aSaveScreen :=  ;
     DC_EXPL( 10,10,15,70,'A Gui SAY Window',,,,,,.t. )
 dc_say(aSaveScreen,2,5,'This is 3/5')
 dc_say(aSaveScreen,4,10,'This is 4/10')
 dc_impl(aSaveScreen)

Files:

_DCEXPL.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_say()
   dc_cls()
   dc_impl()
   dc_explode()
   dc_implode()


dc_explmode()

Enable/Disable exploding windows

Use DC_EXPLMODE(.f.) to disable the exploding process when you want screens to display "instantly" instead of "explode".<br><br> This is particularly useful when running the application on a slower computer. DC_EXPLMODE() affects the operation of the following functions:<br><br> DC_EXPL(), DC_EXPLODE(), DC_IMPL(), DC_IMPLODE()

Syntax:

DC_ExplMode ( <lExplode> ) -> lMode

Returns:

 A logical value.  .T. - Instant On Mode, .F. - Explode Mode.

Arguments:

<lExplode> if .TRUE. will force all windows created with
DC_EXPL() and DC_EXPLODE() to "explode" (default).  If .FALSE.
then all windows will be painted in "instant on" mode.

Examples:

 DC_EXPLMODE( .t. )  // Set instant on mode
 dc_browtile()       // Paint all the browse windows
 DC_EXPLMODE( .f. )  // Set explode mode

Files:

_DCEXPL.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_expl()
   dc_explode()


dc_explode()

Explode a window

DC_EXPLODE() is used to explode a window on the screen with optional border, colors, tone, shadow, etc.

Syntax:

DC_Explode( <nSrow>, ;
            <nScol>, ;
            <nErow>, ;
            <nEcol>, ;
            <cColor1>, ;
            <cColor2>, ;
            [<lTone>], ;
            [<cTitle>], ;
            [<nSlideRate>], ;
            [<lShadow>], ;
            [<lPaintOnly>], ;
            [<lDouble>] ) -> cSaveScreen

Returns:

 A character string that is a "composite" of the coordinates,
 colors, etc. to be used later to restore the screen with
 DC_IMPLODE().

Arguments:

<nSrow>, <nScol>, <nErow>, <nEcol> are the screen coordinates.

<cColor1> is the color of the window frame.

<cColor2> is the color of the window contents.

<lTone> if .TRUE. will create a warning tone.  .FALSE. is
default.

<cTitle> is the a title to display at the top of the box.

<nSlideRate> is a number from 1 to 10 to determine the speed at
which a small box starting at the current cursor location moves
across the screen to start the explode process.  A value of 0
(default) will disable the sliding box. The smaller the number
the faster the sliding box will move.

<lShadow> if .TRUE. (default) will paint a shadow on the
screen.

<lPaintOnly> if .TRUE. will override the setting of
DC_EXPLMODE() and "instantly" paint the box on the screen
rather than "exploding" the box.

<lDouble> if .TRUE. will paint a double line border.  A single
line border (.FALSE.) is default.

Examples:

 cSaveScrn := DC_EXPLODE(5,10,7,70,'B/W','N/W',.F.,;
              ' Enter a Command ',10)
 cCommand := space(50)
 @ 6,12 get cCommand
 read
 dc_implode( cSaveScrn )

Files:

_DCEXPL.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_implode


dc_expressbuttonstyle()

Get or Set the default style for eXpress++ push buttons

DC_ExpressButtonStyle() is a Get-Set function that is used to Set or Get the default configuration object for pushbuttons that are automatically added to eXpress++ windows via the ADDBUTTONS clause of DCREAD GUI command or the BUTTONS clause of the DCGETOPTIONS command.<br><br><br><br><br><br>

Syntax:

DC_ExpressButtonStyle( [<oConfig>] ) -> oOldConfig

Arguments:

<oConfig> is an object of the DC_XbpPushButtonXPConfig() class.

Examples:

oConfig := DC_XbpPushButtonXPConfig():new()

oConfig:radius := 20
oConfig:bgColor := GRA_CLR_CYAN

DC_ExpressButtonStyle( oConfig )

Files:

_dcxbutt.prg, dclipx.dll

See Also:

   dc_xbppushbuttonxpconfig()
   DCREAD
   DCGETOPTIONS


dc_fancybuttonmode()

Enable or disable FANCY pushbuttons

DC_FancyButtonMode() is used to enable or disable FANCY buttons when using the @..DCPUSHBUTTON or DCTOOLBAR commands.<br><br>FANCY buttons are "mouse-aware" pushbuttons that display when the mouse is moved over the static area of the pushbutton.<br><br>

Syntax:

DC_FancyButtonMode( <nMode> ) -> nOldMode

Returns:

A numerical value from 0 to 2.

Arguments:

<nMode> is a numerical value from 0 to 2.

0 - Buttons behave the way they were defined in the DCTOOLBAR
    or @..DCPUSHBUTTON command.  If the FANCY clause was used,
    then the button will be FANCY otherwise it will be NORMAL.

1 - Buttons are all NORMAL.

2 - Buttons are all FANCY.

Examples:

DC_FancyButtonMode(2) // make all buttons FANCY

Files:

_DCGETBX.PRG, DCLIPX.DLL

See Also:

   DCADDBUTTON


dc_fielddel()

Delete a field group from the field group dictionary

DC_FieldDel() is used to delete a field group from the Field Group dictionary file.<br><br>

Syntax:

DC_FieldDel ( [<cFieldGroup>], ;
              [<lImport>] ) -> lStatus

Returns:

A logical .TRUE. if the field group was successfully deleted,
.FALSE. otherwise.

Arguments:

<cFieldGroup> is the name of the field group to delete. If this
parameter is empty, a picklist of all field groups will be
displayed to choose the group to delete.

<lImport> if .TRUE. will display the list of field groups in
the DXFIELDS.DBF (import) dictionary, otherwise the list will
come from the DCFIELDS.DBF dictionary.

Notes:

The DCFIELDS.DBF database and its associated indexes will be created by DC_FieldOpen() if they do not already exist.

Examples:

 // delete a field group from the DXFIELDS.DBF import file.
 cFieldGroup := DC_FieldPick(.t.)
 DC_FieldDel(cFieldGroup,.t.)

Files:

_DCFLDS.PRG, DCLIP1.LIB

See Also:

   dc_fieldedit()
   dc_fieldload()
   dc_fieldsave()
   dc_fieldpick()


dc_fieldedit()

Field Dictionary Editor

DC_FieldEdit() is a field definition editor that maintains the definition of each database field and their browsing, editing and validation properties. The field definitions are stored to an array and/or the DCFIELDS.DBF data- dictionary file.<br><br>DC_FieldEdit() will also update the structure of a database if a field definition has been changed and retain all existing data even if a field type or name has been changed.<br><br>

Syntax:

DC_FieldEdit ( [ <cFieldGroup> | <aFieldGroup> ] )
                -> aFieldGroup

Returns:

 An array consisting of 2 sub-arrays:

 Sub-array #1 contains general information about this field
 group.

 * - Maximum Length allowed, Minimum Length is 0

 Element         Type   Len   Description
 -------------   ----   --- -------------------------------
    1             C       8*  Field Group Name
    2             C      10*  File Alias
    3             C      50*  Field Group Description

 Sub-array #2 contains one sub-array for each field
 definition.

 See DCFIELDS.CH for the definitions of the array elements.

 Element         Type   Len   Description
 -------------   ----   ---   --------------------------------
 DCFLD_ALIAS      C      10*  Alias of database

 DCFLD_NAME       C      10*  Field Name

 DCFLD_TYPE       C       2*  Field Type ( C,D,L,N,M,CA,A,V )

 DCFLD_LEN        N           Field Length

 DCFLD_DEC        N           Field Decimals

 DCFLD_DESC       C      50*  Field Descriptor (used in browse
                              column headings and edit screens)
                              Use semi-colons (;) for multiple
                              lines.
 DCFLD_PROMPT     C     200*  Field Prompt (used in message box)

 DCFLD_PICT       C     100*  Field Picture Clause
                              See Xbase++ TRANSFORM() function

 DCFLD_VALTYPE    C       1   Field Validation Type
                              See DC_FieldValidate() for more info
                              N - None
                              F - Calculated Field
                              X - Logical Expression
                              R - Range
                              D - Database Look-Up
                              T - Table Look-Up
                              V - View (Browse) Look-Up
                              A - Auto-Fill
                              C - Choice
                              E - Case
                              M - Memo Window

 DCFLD_DEFAULT    C     150*  Field Default value code block.
                              Code block must return a value that
                              is the same type as the field.

 DCFLD_WHEN       C     100*  Field When code block.  Code block
                              must return a logical value.  Used
                              to enable/disable field editing based
                              on condition.  Will gray out disabled
                              items.

 DCFLD_PROTECT    C     100*  Field Protect code block.  Code block
                              must return a logical value.  Used
                              to enable/disable field editing based
                              on condition.  Will not gray out
                              disabled items.

 DCFLD_VALID      M      10*  Field Valid Clause or Formula.  This
                              must be a code block that returns a
                              logical value or a set of parameters
                              separated by the | delimeter.  The
                              parameters must conform to the type
                              of validation.  See DCFLD_VALTYPE
                              above.

 DCFLD_EMPTY      L           Empty Value Allowed

 DCFLD_EDIT       L           Editing Allowed

 DCFLD_ACCESS     C       5*  Access Key

 DCFLD_SORT       N           Sorting element (reserved)

 DCFLD_HELPCODE   C      22*  Help Code

 DCFLD_EDOPT      C      50*  Edit Option String

 DCFLD_VALUE      X           Place to store Old Field Value

 DCFLD_OLDNAME    C      10*  Old field name

 DCFLD_OLDTYPE    C       2*  Old field type

 DCFLD_ENCRYPT    C       8*  Encryption password

 DCFLD_PROGRAM    C           Program Validation (memo)

 DCFLD_FLAG       L       1   Logical flag (reserved)

 DCFLD_COMPILE    C     100*  Compile Code Block.  Must return
                              a logical value.  Used to enable
                              or disable inclusion of this
                              field in data-entry screen based
                              on a condition.

 DCFLD_FONT       C      50*  Default Font Compound Name

 DCFLD_TOOLTIP    C     100*  ToolTip.  Use semicolons for
                              multiple lines.  May also be a
                              code block.

 DCFLD_CARGO      A           Cargo Array

 DCFLD_ORDER      N           Field Order in Database

 DCFLD_POPUP      C     100*  PopUp Code Block.  Must return a
                              value that is the same type as
                              the field.  This code block
                              receives the value of the GET as
                              a parameter.  The code block is
                              evaluated when the user clicks on
                              the PopUp button next to the GET.

Arguments:

<cFieldGroup> | <aFieldGroup> is the name of the field group
in DCFIELDS.DBF to load and edit (up to 8 characters) or
<aFieldGroup> is a Field Group array.  See RETURNS for a
specification of this array.  If no parameter is passed, a
pick-list of all Field Groups in DCFIELDS.DBF will be displayed.

Notes:

The DCFIELDS.DBF database and its associated indexes will be created by DC_FieldOpen() if they do not already exist.

Examples:

 -- Example 1 --
 // Load a field group from the dictionary and edit it //
 DC_FIELDEDIT()

 -- Example 2 --
 // Edit field group "CUSTOMER"
 DC_FIELDEDIT("CUSTOMER")

 -- Example 3 --
 // Edit a field group array //
 aFieldGroup := DC_FieldPick()
 aFieldGroup := DC_FIELDEDIT( aFieldGroup )

Files:

_DCFLDS.PRG, DCLIP1.LIB

See Also:

   dc_fieldload()
   dc_fieldvalidate()


dc_fieldload()

Load a field Group Array from the Field Dictionary

DC_FieldLoad() is used to retrieve a field group from the DCFIELDS.DBF field group dictionary and store it to an array.<br><br><br><br>

Syntax:

DC_FieldLoad ( [<cGroupName>], ;
               [<lCache>], ;
               [<lMessage>], ;
               [<lCreateDbf>], ;
               [<lErrorOk>], ;
               [<lImport>] ) -> aFieldGroup

Returns:

An array consisting of 2 sub-arrays:

See the RETURNS section of DC_FieldEdit() for a specification
of this array.

Arguments:

<cGroupName> is the name of the field group in DCFIELDS.DBF
to load (up to 8 characters).  If no parameter is passed, a
pick-list of all Field Groups in the DCFIELDS.DBF dictionary
will be displayed.

<lCache> if .TRUE. (default) will save the group to a static
(cache) array so the next time it is requested it will
be reloaded from the cache for faster speed.  If .FALSE. then
it will not be saved to the static array.

<lMessage> if .TRUE. (default) will display an error message
if the Field Group could not be loaded or does not exist
in the dictionary file.  If .FALSE, then no error message
will be displayed.

<lCreateDbf> if .TRUE. (default) will create any empty
DCFIELDS.DBF if it cannot be found.  If .FALSE. the
database will not be created.

<lErrorOk> if .FALSE. (default) will return a NIL if the
field array being loaded does not match the structure of the
currently selected database.  If .TRUE. then the field array
loaded from the dictionary will always be returned.

<lImport> if .TRUE. will attempt to load the array from a
an import file named DXFIELDS.DBF.  If .FALSE. (default) then
the array will be loaded from the standard DCFIELDS.DBF
dictionary.

Notes:

The DCFIELDS.DBF database and its associated indexes will be created by DC_FieldOpen() if they do not already exist.

Examples:

 aFieldGroup := DC_FIELDLOAD()
 aFieldGroup := DC_FieldEdit( aFieldGroup )
 DC_FieldSave( aFieldGroup )

Files:

_DCFLDS.PRG, DCLIP1.LIB

See Also:

   dc_fieldedit()
   dc_fieldvalidate()
   dc_fieldsave()


dc_fieldpick()

Choose a field group or browse the field group dictionary

DC_FieldPick() is used to pop up a list of field groups in the field group dictionary.<br><br><br><br>

Syntax:

DC_FieldPick ( [<cTitle>], ;
               [<lImport>], ;
               [@<aGroupList>], ;
               [<lNoPick>] ) -> cGroupName

Returns:

A Character string containing the name of the chosen group.
This will contain a null string if <lNoPick> is .TRUE. or if
the operator aborts the choice.

Arguments:

<cTitle> is the title to display in the pick list window.

<lImport> if .TRUE. will display the list of field groups in
the DXFIELDS.DBF (import) dictionary, otherwise the list will
come from the DCFIELDS.DBF dictionary.

@<aGroupList> is a variable, passed by reference, to store an
array of all group names and descriptions.

<lNoPick> if .TRUE. is used in conjunction with <aGroupList>.
This is used to only return the array of Group names and not
display the picklist.

Notes:

The DCFIELDS.DBF database and its associated indexes will be created by DC_FieldOpen() if they do not already exist.

Examples:

 cFieldGroup := DC_FieldPick()
 aFieldGroup := DC_FieldLoad(cFieldGroup)
 aFieldGroup := DC_FieldEdit( aFieldGroup )
 DC_FIELDSAVE( aFieldGroup )

Files:

_DCFLDS.PRG, DCLIP1.LIB

See Also:

   dc_fieldedit()
   dc_fieldload()
   dc_fieldsave()


dc_fieldsave()

Save a Field Group Array to the Field Dictionary

DC_FieldSave() is used to save a field array to the DCFIELDS.DBF field group dictionary.<br><br><br><br>

Syntax:

DC_FieldSave ( <aFieldGroup>, ;
               [<lExport>] ) -> lStatus

Returns:

A logical .TRUE. if the field group was successfully saved,
.FALSE. otherwise.

Arguments:

<aFieldGroup> is a field group array that conforms to the
specification in the RETURNS section of DC_FieldEdit().

<lExport> if .TRUE. will save the field group to a file named
DXFIELDS.DBF, otherwise it will be save to DCFIELDS.DBF.

Notes:

The DCFIELDS.DBF database and its associated indexes will be created by DC_FieldOpen() if they do not already exist.

Examples:

 aFieldGroup := DC_FieldLoad()
 aFieldGroup := DC_FieldEdit( aFieldGroup )
 DC_FIELDSAVE( aFieldGroup )

Files:

_DCFLDS.PRG, DCLIP1.LIB

See Also:

   dc_fieldedit()
   dc_fieldvalidate()
   dc_fieldload()


dc_fieldvalidate()

Validate a value in a field during data entry

DC_FieldValidate() is used to validate the value entered into a field during data entry. Validation types are entered in the field editor using DC_FieldEdit().

Syntax:

DC_FieldValidate ( <xFieldGet>, ;
                   <aFields>, ;
                   <nPos>, ;
                   [<lPopUp>] ) -> lValid

Returns:

A logical .TRUE. if the field validates, otherwise a logical
.FALSE.

Arguments:

<xFieldGet> is the value to validate.  This is the value from
the data entry GET.

<aFields> is a field array that conforms to the specification
for a field array created by DC_FieldEdit().  The field array
defines all the properties of all fields for the currently
selected work area including validation types and formulas.

<nPos> is the field position in the Field Array that points to
the field being validated.

<lPopUp> if .TRUE. will force picklists to be displayed even if
the field validates correctly.

Notes:

Validation Types:

Validations are entered as formulas. Each validation type requires a different formula. A formula is simply a list ofparameters separated by the vertical bar | character. TheValidation type and formula are entered into the Field Arrayby using the Field Editor : DC_FieldEdit() or the dot promptcommand FIELD EDIT.

An easier method of entering the formula and preventing mistakesis to use the FORMULA EDITOR by pressing CTRL-ENTER or clickingon the PopUp button after the formula field in the field editor.

==============================================================

VALIDATION TYPE X - Expression

Validation type "X" is used to evaluate an expression that returns a logical .TRUE. or .FALSE. based on the operator input and/or other field data. When entering the VALIDATION FORMULA, it must be a valid expression that when macro-expanded, returns a "logical" value of .TRUE. for a valid entry or a .FALSE. for an invalid entry.

For example you may have a field named "HOURS" that is allowed to have a range of 0-4 when the DATE field has a week-end date or a range of 0-8 when the DATE field has a weekday date. The expression for creating this type of validation is:

IIF(DOW(DATE)=1.OR.DOW(DATE)=7,HOURS<=4,HOURS<=8)

If the operator attempts to enter more than 8 hours for a weekday or more than 4 hours for a weekend, a message similar to the following will appear:

"Invalid Input. Must meet following Condition"

==============================================================

VALIDATION TYPE V - Browse Lookup

Validation type "V" is used to seek a value from another database based on a passed value and then optionally choose a value from a BROWSE pick-list whose configuration was previously created and stored in the DCBROWSE.DBF Browse Catalog using the BROWSE editor.

If the entered value already matches a "seek" value in the target database, or if the "allow override" flag is "YES", then the database browse will not be displayed unless the operator clicks on the popup button at the end of the field when in data-entry mode or presses CTRL-ENTER when editing the field. A "V" validation also provides for moving data between fields of different databases upon completion of the successful validation by referencing a previously created "Field Map".

Param 1 - The TAG NAME of the "Look-Up" FILE GROUP that must be opened for performing this validation. This must be a valid File Group Name in the DCFILES.DBF database that was assigned by the FILE EDITOR via the command "FILE EDIT" or the function "DC_FILEEDIT()". A FILE GROUP is a set of database files, indexes and/or relations required to perform the validation. If no TAG NAME is entered, then it is assumed that the "Look-Up" file is already opened.

Param 2 - The TAG NAME of the "Look-Up" BROWSE CONFIGURATION to use for choosing a record from the target (Look-Up) database(s). This must be a valid Browse Configuration in the DCBROWG.DBF database that was assigned by the BROWSE EDITOR from the command "BROWSE GUI" or the function "DC_BrowseGuiDb()". If NO Tag Name is entered, then a DEFAULT BROWSE will be created for the target (Look-Up) database that will consist of all database fields.

Param 3 - The FILE ALIAS of the "Look-Up" File to select for performing the validatiion.

Param 4 - The SEARCH INDEX NUMBER of the controlling index to use when "seeking" to the record in the "Look-Up" database. The key of this index must match the value of the Look-Up field or Expression to seek the value.

Param 5 - The LOOK-UP FIELD OR EXPRESSION to use for extracting the value to "seek" in the "Look-Up" database. This expression must return a value of the same type as the index key of the controlling index to seek the value.

Param 6 - The RETURN FIELD OR EXPRESSION to use for extracting the value to return into the field being validated. This expression must return a value of the same type as the database field being validated.

Param 7 - START SCOPE Expression or Code Block. This is an optional expression or code block that when evaluated returns a value that matches the type of the selected index for the top scope value or first record to be displayed in the browse window.

Param 8 - STOP SCOPE Expression or Code Block. This is an optional expression or code block that when evaluated returns a value that matches the type of the selected index for the bottom scope value or last record to be displayed in the browse window.

Param 9 - A Y for YES or N for NO to establish whether or not the operator is allowed to OVERRIDE the value returned from the browse. If YES and the operator presses ESCAPE, then nothing is returned, otherwise if NO then the selected value is returned regardless of the method of exiting the browse by the operator.

Param 10 - The 'optional' FIELD MAP TAG NAME to use for moving information from the Look-Up database to the current database or from any other open database to any other open database. This must be a valid field map tag name that exists in the DCMAPS.DBF database which is maintained by the command "FMAP EDIT" or the function "DC_FMAPEDIT()".

Param 11 - The 'optional' FIELD NAME to extract information to pass to the FIELD MAP as the FIELD MAP SUBGROUP. Only the items in the Field Map that match the value in this field will be evaluated when performing the mapping process. This parameter is ignored if parameter 9 is empty.

NOTE: A type "V" validation will leave the Look-up database record pointer at the record selected by the operator or at the record automatically found that matches the data entered in the field. This record can then be used to transfer information from any set of fields in the Look-Up database to any set of fields in the current database by using a type "A" validation on each field.

An easier method of entering the formula and preventing mistakes is to use the FORMULA EDITOR by pressing CTRL-ENTER, clicking the popup button or leaving the formula empty. The FORMULA EDITOR reads the existing formula and provides a series of data- entry fields and pick-lists to simplify the creating of validations.

Example:

Look-up Files Tag :CUSTOMER : Look-up Browse Tag :CUSTOMER1 : Look-up File Alias :CUSTOMER : Look-up Index # : 2: Look-up Field/Expr :CUST_NMBR : Return Field/Expr :CUST_NMBR : Start Scope : {||INVOICE->CUST_NMBR} Stop Scope : {||INVOICE->CUST_NMBR} Allow Override? :N:

==============================================================

VALIDATION TYPE T - Code Table Lookup

Validation type "T" is used to choose a value from a code table in the DCCODES.DBF Code-Table dictionary and enter it into the field. If the entered value already matches a value in the code table, or if the "allow override" flag is "YES", then the pick-list of codes will not be displayed unless the operator clicks on the popup button at the end of the field or presses CTRL-ENTER when editing the field.

A "T" validation also provides for moving data between fields of different databases upon completion of the successful validation by referencing a previously created "Field Map".

Example of a Code-Table table:

1B First Base 2B Second Base 3B Third Base P Pitcher SS Short Stop RF Right Field LF Left Field CF Center Field C Catcher DH Designated Hitter

When the operator chooses an item from the code-table pick-list, the value in the CODE field of the DCCODES.DBF database item selected will be returned into the data field. Code-Tables are allowed only for validating character-type fields.

Param 1 - The CODE TABLE name to open.

Param 2 - A Y for YES or N for NO to establish whether or not the operator is allowed to OVERRIDE the value returned from the browse. If YES and the operator presses ESCAPE, then nothing is returned, otherwise if NO then the selected value is returned regardless of the method of exiting the pick-list by the operator.

Param 3 - An 'optional' FIELD MAP TAG NAME to use for moving information from the Code Table database to the current database or from any other open database to any other open database. This must be a valid field map tag name that exists in the DCMAPS.DBF database which is maintained by the command "FMAP EDIT" or the function "DC_FMAPEDIT()". The value returned by the code table will be passed to the Field Mapping routine to select a mapping "Sub-Group". If the Map data does not include Sub-Groups, then all items in the map will be evaluated.

Param 4 - TOKENIZED LIST. Enter a Y if you want each pick from the code table to be appended to the value in the GET as a list of tokens rather than replacing the value in the GET with the selected code.

Param 5 - Enter the delimeter to use between the tokens.

NOTE: A type "T" validation will leave the DCCODES.DBF database (code-table) record pointer at the selected code table record. This record can then be use to transfer the value in CODE_DESC to any other field using a type "A" validation.

Example:

Code Table No. :BASEBALL : Allow Override? :N: Field Map Tag : : Tokenized List? : Y Token Delimiter : ,

==============================================================

VALIDATION TYPE R - Range

Validation type "R" is used to validate that the entered field value falls between a specified range of values. If the operator fails to enter a proper value, an error message similar to "Entry must be in the Range between 100 and 500" will be displayed and the operator will not be allowed to exit the field other than by entering a correct value or pressing ESCape.

Example :

Starting Range :100 : Ending Range :500 :

==============================================================

VALIDATION TYPE P - Program

Validation type "P" is used to validate a field entry based on the results returned by executing a specified program. The program may be a function that is linked into the .EXEcutable engine or an "interpreted" program that exists in the DCPROG.DBF program catalog. The program may return a value to place into the field or a logical value to validate proper data input.

To create a type "P" validation, enter "P" as VALIDATION TYPE when using the FIELD EDITOR via the command "FIELD EDIT" or function "DC_FIELDEDIT()". When entering the VALIDATION FORMULA, each formula item is separated by a vertical bar | character.

Item 1 - The PROGRAM NAME. This is a program name of up to 10 characters. This program must exist in the DCPROG.DBF Program Catalog. To create or maintain this program use the command "PROGRAM MAINTENANCE" or the function "DC_PROGMAINT()". If you wish to use a compiled and linked function rather than an interpreted program, then include parenthesis () after the PROGRAM NAME. If you wish to write a small program and save it in the memo field of the field dictionary enter "MEMO".

Item 2 - Enter Y for YES or N for NO if this is a LOGICAL validation rather than a return value. A LOGICAL validation returns a .TRUE. or .FALSE. to validate whether or not the data-entry was valid. If a .FALSE. is returned, then the operator will not be allowed to move to the next field until a valid input is received. If a NO is entered, then it is assumed that the program is returning a value that is the same type as the field being validated and that this value will be placed into the field.

Items 3 thru 17 - Enter up to 15 PARAMETERS to pass to the program. These may be literal values, functions, field names, or expressions. Each value in each item will be macro-expanded before being passed on to the program.

==============================================================

VALIDATION TYPE I - Increment on Append

Validation type "I" is used to assign a default value to a field, when appending a new record to the database, that is equivalent to an "incremented" value extracted from another field in the same database or any other database. For example, if you wish to automatically assign a new invoice number to a new record, a type "I" validation can be used to go to the last record of the file, extract the last invoice number, increment it by a value of 1 and store the new value in the field. Type "I" validations will increment both character and numeric fields.

Examples:

Type Last Value Incremented Value ---- ---------- ----------------- N 2345 2346 C 56710 56711 C AX-389-BL AX-390-BL

Param 1 - The FILE ALIAS NAME of the "Look-Up" FILE that must be opened for extracting the last value. This must be a valid ALIAS for a file that is already opened when the record is being added. Leave this parameter empty if extracting a value from the last record in the current database.

Param 2 - The LOOK-UP FIELD OR EXPRESSION to use for extracting the value to "seek" in the "Look-Up" database. This expression must return a value of the same type as the index key of the controlling index to seek the value. Leave this parameter empty if extracting a value from the last record in the current database or if the record is already at the correct location, such as a 1-record "SYSTEM.DBF".

Param 3 - The RETURN FIELD OR EXPRESSION to use for extracting the value to return and increment into the field being initialized. This expression must return a value of the same type as the database field being validated. Leave this parameter empty if extracting a value from the last record in the current database. If not extracting a value from the current database, then the new value will be stored in the return field of the related database in addition to the storing in the validated field of the current database.

Param 4 - The SEARCH INDEX NUMBER of the controlling index to use when "seeking" to the record in the "Look-Up" database. The key of this index must match the value of the Look-Up field or Expression to seek the value. Leave this as 0 if the record in the Look-up database does not need to be seeked.

Param 5 - The DEFAULT or STARTING value to enter into the database field in the event that an empty value is returned from the target (Look-Up) database.

Example :

Lookup File Alias :DCFILES : Lookup Field/Expr :"INVOICE" : Return Field/Expr :REF_NO : Seek Index No. : 1: Start Value : IN-10001 :

==============================================================

VALIDATION TYPE F - Calculate value from Expression

Validation type "F" is used to calculate a value from an expression that includes references to other fields in the database and automatically insert the value returned by the expression. Use a type "F" validation to update "non- entry" fields whenever the value in another field changes. When entering the VALIDATION FORMULA, it must be a valid expression that when macro-expanded, returns a value of the same "type" as the field being validated.

For example you may have a field named "HOURS" that is automatically filled-in whenever the operator changes the value of another field named "MINUTES". The expression for creating this type of calculation is: MINUTES/60.

Example :

Formula :MINUTES/60 :

==============================================================

VALIDATION TYPE C - Choice from Pick List

Validation type "C" is used to choose a value from a pick-list table of up to 15 choices. If more than 15 choices are required, then use Validation type "T". If the entered value already matches a value in the choice pick-list, or if the "allow override" flag is "YES", then the pick-list of choices will not be displayed unless the operator clicks on the popup button at the end of the field or presses CTRL-ENTER when editing the field.

When the operator chooses an item from the pick-list, the number of characters in the chosen item will be truncated (cut-off) to the length of the field. Choice Pick-lists are allowed only for character-type fields.

Example:

Choice # 1 :1B - First Base : Choice # 2 :2B - Second Base : Choice # 3 :3B - Third Base : Choice # 4 :P - Pitcher : Choice # 5 :SS - Short Stop : Choice # 6 :RF - Right Field : Choice # 7 :LF - Left Field : Choice # 8 :CF - Center Field : Choice # 9 :C - Catcher : Choice #10 :DH - Designated Hitter : Choice #11 : : Choice #12 : : Choice #13 : : Choice #14 : : Choice #15 : : Allow Override? :Y:

==============================================================

VALIDATION TYPE A - AutoFill

Validation type "A" is used to automatically fill the field with a value from a relational file after the operator entered data in an associated field in the field list. A type "A" validation is also referred to as "AUTOFILL" and must also be associated with a type "V" "D", or "T" validation elsewhere in the data-field table. AUTOFILL validations are "triggered" by a "V", "D", or "T" validation in the following manner:

1. The operator chooses a record from a relational file or a code table while validating a field that has a type "V" or "T" validation. After the data record is selected from the relational file, a pointer to the relational file is stored away in a variable, the relational file remains open, and the record pointer in the relational file is pointing to the selected record.

2. The field list is then scanned to see if there are any fields with type "A" validations that also have a reference to the field name that triggered the "V" or "T" validation. For each field that has a reference, the data from the specified relational file field will be written to that field.

Fields that have been filled by an AUTOFILL validation may be overwritten when the field is entered provided that it is an "editable" field.

Param 1 - The name of the field in the field list that triggered the AUTOFILL with a type "V" or "T" validation.

Param 2 - The name of the field in the relational file chosen by the type "V" or "T" validation that contains the data to be written to this field. If the "V" or "T" validation uses only a single relational file then it is not necessary to use the alias in front of the field name, however, it is always a good idea.

Example:

Lookup Field/Expr :CUST_NMBR : Return Field/Expr :CUSTOMER->NAME :

Examples:

FUNCTION XTest()

/* This example shows how to use the field dictionary to
   display a data-driven browse and data-entry screen */

LOCAL GetList := {}, i, aFieldGroup, oBrowse, cAlias, aFieldOpt, ;
      aFieldItems, oTabPage1, oTabPage2, oTabPage2Static, bGetSet, ;
      bKeyBlock, bPopUp, GetOptions, bCompile

DC_FileRest('COLLECT')
aFieldGroup := DC_FieldLoad('COLLECT')
aFieldOpt := aFieldGroup[1]
aFieldItems := aFieldGroup[2]
cAlias := 'COLLECT'

@ 0,0 DCTABPAGE oTabPage1 SIZE 84,18 CAPTION 'Browse' ;
      GOTFOCUS {||oBrowse:RefreshAll()}

@ 0,0 DCTABPAGE oTabPage2 RELATIVE oTabPage1 CAPTION 'Edit' ;
      STATICAREA oTabPage2Static ;
      GOTFOCUS {||DC_RecLock(), ;
                  DC_GetRefresh(GetList)}

@ 2,2 DCBROWSE oBrowse SIZE 80,15 ALIAS 'COLLECT' ;
   PRESENTATION DC_BrowPres() PARENT oTabPage1

FOR i := 1 TO Len(aFieldItems)

  bCompile := DC_GetBlock(aFieldItems[i,DCFLD_COMPILE])
  IF Valtype(bCompile) = 'B' .AND. !Eval(bCompile)
    LOOP
  ENDIF

  DCBROWSECOL DATA &('{||' + cAlias + '->' + ;
       aFieldItems[i,DCFLD_NAME] + '}') ;
     PARENT oBrowse HEADER aFieldItems[i,DCFLD_DESC] ;
     MESSAGE aFieldItems[i,DCFLD_PROMPT] ;
     PROTECT aFieldItems[i,DCFLD_PROTECT] ;
     WHEN aFieldItems[i,DCFLD_WHEN] ;
     FONT aFieldItems[i,DCFLD_FONT] ;
     HELPCODE aFieldItems[i,DCFLD_HELPCODE]

  IF aFieldItems[i,DCFLD_TYPE] = 'M'
    bGetSet := 'MEMO'
    bKeyBlock := {|a,b,o|o:undo()}
    bPopUp := MemoBlock(i,cAlias,aFieldItems[i,DCFLD_DESC])
  ELSE
    bGetSet := DC_FieldWBlock(aFieldItems[i,DCFLD_NAME],cAlias)
    bKeyBlock := nil
    IF !Empty(aFieldItems[i,DCFLD_POPUP])
      bPopUp := aFieldItems[i,DCFLD_POPUP]
    ELSEIF aFieldItems[i,DCFLD_VALTYPE] $ 'TCVD' // table, choice, view, datapick
      bPopUp := PopupBlock(i,aFieldItems)
    ELSEIF aFieldItems[i,DCFLD_TYPE] = 'D'
      bPopUp := {|d|DC_PopDate()}
    ELSE
      bPopUp := nil
    ENDIF
  ENDIF

  @ i-.5,2 DCSAY aFieldItems[i,DCFLD_DESC] ;
     GET bGetSet ;
     POPUP bPopUp ;
     PARENT oTabPage2Static ;
     KEYBLOCK bKeyBlock ;
     PICTURE aFieldItems[i,DCFLD_PICT] ;
     MESSAGE aFieldItems[i,DCFLD_PROMPT] ;
     EDITPROTECT aFieldItems[i,DCFLD_PROTECT] ;
     WHEN aFieldItems[i,DCFLD_WHEN] ;
     VALID ValidBlock(i, aFieldItems, ;
        aFieldItems[i,DCFLD_VALTYPE],aFieldItems[i,DCFLD_VALID],cAlias) ;
     HELPCODE aFieldItems[i,DCFLD_HELPCODE] ;
     GETFONT aFieldItems[i,DCFLD_FONT]

NEXT

@ 18,0 DCMESSAGEBOX TYPE XBPSTATIC_TYPE_RECESSEDBOX ;
       FONT '12.Arial Bold' COLOR GRA_CLR_DARKBLUE ;
       SIZE 84,1.2

DCGETOPTIONS SAYWIDTH 150 SAYRIGHT AUTORESIZE
DCREAD GUI FIT ADDBUTTONS MODAL ;
   TITLE aFieldOpt[DCFLDGROUP_DESC] ;
   CLEAREVENTS ;
   OPTIONS GetOptions ;
   EVAL {|o|SetAppWindow(o)}

RETURN nil

* -----------------------------

STATIC FUNCTION MemoBlock( i, cAlias, cDesc )

RETURN {|c,x|x:=(cAlias)->(FieldGet(i)), ;
          x:=DC_MemoBase(x,{,,,,,,,,,,,,,'Editing Memo: ' + cDesc}), ;
          FieldPut(i,x),c}

* -----------------------------

STATIC FUNCTION PopUpBlock( i, aFieldItems )

RETURN {|c|DC_FieldValidate(@c, aFieldItems, i, .t. ),c}

* -----------------------------

STATIC FUNCTION ValidBlock( i, aFieldItems, cValtype, cFormula, cAlias )

IF Empty(cValtype)
  RETURN cFormula
ENDIF

RETURN {||DC_FieldValidate( (cAlias)->(FieldGet(i)),
          aFieldItems, i ) }
*

Files:

_DCFLDSV.PRG, DCLIP1.LIB

See Also:

   dc_fieldload()


dc_fieldwblock()

A replacement for FieldWBlock() for debugging

DC_FieldWBlock() is a debugging replacement for the Xbase++ function FieldWBlock().<br><br>The code block function FieldWBlock() creates a code block providing (when it is evaluated) read and write access to a field in the specified work area. If no value is passed to the code block when it is evaluated, the current value from the field <cFieldName> is read and returned. Otherwise, the code block writes the passed value into the field and returns this new value. <br><br>When FieldWBlock() is called, no file needs to be opened in the specified work area. However, when the code block is evaluated, the file containing the field the code block is accessing must be open. If the field <cFieldName> does not exist when the code block is evaluated, a runtime error occurs. <br><br>The replacement function DC_FieldWBlock() includes a call to a debugging function which echoes call stack information and read/write information into a debug window whenever the codeblock is evaluated. Debugging event driven programs that use Get/Set codeblocks can be cumbersome. Often times a Get/Set codeblock may be called more times than desired thereby affecting performance. This is usually the case when refreshing systems are used. The display of debugging info is enabled and/or disabled by the DC_FieldWDebug() function.<br><br>

Syntax:

DC_FieldWBlock( <cFieldName>, ;
                [<cAlias>] ) -> bGetSet

Arguments:

<cFieldName> is a character string containing the name of the
field whose data the code block will read or modify.

<cAlias> is a character string containing the alias name for
the work area holding the field which the code block will
access.  If this parameter is NIL then the alias of the current
work area will be used.

Examples:

/* In this example, every time the field COLLECT->TYPE
   is updated during cell-editing, information about
   the field will be echoed to the debug window */

FUNCTION Xtest()

LOCAL GetList := {}, oBrowse

USE COLLECT VIA DBFNTX
DC_FieldWDebug(.t.,'TYPE',.t.)

@ 0,0 DCBROWSE oBrowse ALIAS 'COLLECT' SIZE 50,9 ;
   EDIT xbeBRW_ItemSelected

DCBROWSECOL DATA DC_FieldWBlock( 'descrip', 'collect' ) ;
   PARENT oBrowse WIDTH 20 HEADER 'Description'

DCBROWSECOL DATA DC_FieldWBlock( 'type', 'collect' ) ;
   PARENT oBrowse WIDTH 10 HEADER 'Type'

DCREAD GUI FIT ADDBUTTONS

RETURN nil

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_fieldwdebug()


dc_fieldwdebug()

Enable debug window for Get/Set field code blocks

DC_FieldWDebug() is used to establish the debugging mode when using DC_FieldWBlock() for creating Get/Set code blocks.<br><br>

Syntax:

DC_FieldWDebug( <lDebugOn>, ;
                [<cFieldName>], ;
                [<lWriteOnly>] ) -> lStatus

Returns:

NIL.

Arguments:

<lDebugOn> is a logical .TRUE. to turn the debug window ON, a
logical .FALSE. to turn it OFF.

<cFieldName> is an optional character string.  This is the name
of a field to debug when there are many code blocks that all
use DC_FieldWBlock() and you only want to see Get/Set transactions
that relate to a specific field, otherwise all Get/Set transactions
will be echoed to the debug window.

<lWriteOnly> is an optional logical value.  Set this to .TRUE.
if you want to only see Get/Set transactions that write to the
field.

Examples:

/* In this example, every time the field COLLECT->TYPE
   is updated during cell-editing, information about
   the field will be echoed to the debug window */

FUNCTION Xtest()

LOCAL GetList := {}, oBrowse

USE COLLECT VIA DBFNTX
DC_FieldWDebug(.t.,'TYPE',.t.)

@ 0,0 DCBROWSE oBrowse ALIAS 'COLLECT' SIZE 50,9 ;
   EDIT xbeBRW_ItemSelected

DCBROWSECOL DATA DC_FieldWBlock( 'descrip', 'collect' ) ;
   PARENT oBrowse WIDTH 20 HEADER 'Description'

DCBROWSECOL DATA DC_FieldWBlock( 'type', 'collect' ) ;
   PARENT oBrowse WIDTH 10 HEADER 'Type'

DCREAD GUI FIT ADDBUTTONS

RETURN nil

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_fieldwblock()


dc_filearray()

Capture work area(s) to a file definition array

DC_FILEARRAY() will return a file definition array of file information captured from the current work area. A file definition array is used to define files, indexes and relations for later restoring the work areas from the contents of the array.

Syntax:

DC_FileArray ( [<lAllAreas>] ) -> aFileGroup

Returns:

 An array consisting of three sub-arrays:

 Sub-array #1 is an array of two elements: Element #1
 contains the ALIAS() of the current work area and element
 #2 is a null string.

 Sub-array #2 is a 2-dimensional array consisting of one
 sub-array for each file, index or relation.  See RETURNS in
 the documentation of DC_FILEEDIT() for a definition of this
 array.

 Sub-array #3 is a set of 3 sub-arrays:
 Element #1 is an array containing the current Browse
 configuration of all work areas (DCBROWSE).
 Element #2 is an array containing the current Edit
 configuration of all work areas (DCEDIT).
 Element #3 is an array containing the current Import
 configuration of all work areas (DCIMPORT).

Arguments:

<lAllAreas> if .TRUE. (default) will also include all the
files in all open work areas, otherwise only the files in the
currently selected area will be returned in the array.

Examples:

 use customer shared readonly
 set index to custname, custnmbr
 aFileGroup := DC_FILEARRAY()

Files:

_DCFILES.PRG

See Also:

   dc_fileedit()
   dc_filerest()


dc_filecompare()

Compares the contents of two files

DC_FileCompare() is used to do a byte by byte comparison of the contents of two files.<br><br>

Syntax:

DC_FileCompare( <cFile1>, <cFile2> ) -> lStatus

Returns:

A logical .TRUE. if the files are identical, .FALSE. otherwise.

Arguments:

<cFile1> and <cFile2> are the full path names of the two files
to compare.

Files:

_DCFUNCT.PRG, DCLIPX.DLL


dc_filecopy()

Copy or move a set of files to a common location

DC_FileCopy() is used to copy or move a set of files to a common location.<br><br>This function displays a dialog window with a progress bar and an option to cancel the copy or move.<br><br>This function is handy when there are a set of very large files that could take a lot of time to copy or move across a network path.<br><br>

Syntax:

DC_FileCopy( <aFile>, ;
             <cToPath>, ;
             <aMessage>, ;
             @<aErrors>, ;
             <lMove> ) -> lStatus

Returns:

A logical .TRUE. if all files were successfully copied or moved, .FALSE.
otherwise.

Arguments:

<aFile> is a single-dimensional array of fully-pathed file names.

<cToPath> is the full path of the directory that receives the files.

<aMessage> is a single-dimensional array of message strings to display
in the dialog window.

@<aErrors> is an array that receives error information.

<lMove> if .TRUE. will MOVE the files to the new location, otherwise
they will be copied.

Files:

_DCFUNCT.PRG, DCLIPX.DLL


dc_filedel()

Delete a file group from the DCFILES.DBF dictionary

DC_FileDel() is used to delete a file group from the DCFILES.DBF file dictionary.

Syntax:

 DC_FileDel( [<cFileGroup>] ) -> lStatus

Returns:

 A logical .TRUE. if the file group was successfully deleted.

Arguments:

<cFileGroup> is the name of the file group in DCFILES.DBF
to delete (up to 8 characters).

Examples:

 // Delete the file group named JUNK
 DC_FileDel('JUNK')

Files:

_DCFILES.PRG

See Also:

   dc_fileedit()


dc_fileedit()

A Database File / Work area Definition editor

DC_FILEDEDIT() is an editor that maintains the definition of each database and it's indexes and relations.<br><br> Each file group is stored in the DCFILES.DBF dictionary file. A file group contains all the information necessary to restore work areas for editing and browsing. The data dictionary contains information for opening databases and indexes (or creating indexes that do not exist).

Syntax:

 DC_FileEdit( [<acFileGroup>] ) -> aFileGroup

Returns:

 An array consisting of 2 sub-arrays:

 See DCFILES.CH for the definitions of the array elements.

 Sub-array #1 contains general information about this file
 group.

 * - Maximum Length allowed, Minimum Length is 0

 Element           Type   Len   Description
 -------------     ----   ---   ------------------------------
 DCFILE_GROUPNAME    C      8*  File Group Name
 DCFILE_GROUPDESC    C     50*  File Group Description
 DCFILE_GROUPDEFA    C    100*  Default Directory for files

 Sub-array #2 contains one sub-array for each file, index
 or relation definition.

 Element         Type   Len   Description
 -------------   ----   ---   --------------------------------
 DCFILE_TYPE      C       1   Item Type
                              E - Open Database exclusive
                              S - Open Database shared
                              I - Open Index
                              R - Set a relation
                              F - Open a File Group
 DCFILE_NAME      C     150*  File Name
 DCFILE_DESC      C      50*  Description of File
 DCFILE_ALIAS     C      10*  Alias Name
 DCFILE_RELALIAS  C      10*  Relational Alias Name
 DCFILE_FIELD1    C      10*  Relational Field
 DCFILE_KEY       C     300*  Index Key Expression
 DCFILE_RECNO     N           Database record to select
 DCFILE_FILTER    C     500*  Database filter expression
 DCFILE_RDD       C      10*  Name of RDD (Data-Driver to use)
 DCFILE_SUPERRDD  C      10*  Name of SUPER RDD (Data-Driver)
 DCFILE_INDEXNO   N           Index Order to select
 DCFILE_TAGNAME   C      10*  Index Tag Name to select
 DCFILE_INDEXFOR  C     500*  Index Condition expression
 DCFILE_DESCEND   L           Descending Index - .T.
 DCFILE_UNIQUE    L           Unique Index - .T.
 DCFILE_ISCDX     L           Combined Index - .T.
 DCFILE_BROWSE    C      10*  Browse Configuration Name
 DCFILE_EDIT      C      10*  Edit (Data-Entry) Configuration
 DCFILE_IMPORT    C      10*  Import Configuration
 DCFILE_DICT      C           Unused (reserved)

Arguments:

<acFileGroup> is the name of the file group in DCFILES.DBF
to load and edit (up to 8 characters) or <acFileGroup> is a
File Group array.  See RETURNS for a specification of this
array.  If no parameter is passed, a pick-list of all File
Groups in DCFILES.DBF will be displayed.

Examples:

 -- Example 1 --
 // Load a file group from the dictionary and edit it //
 DC_FILEEDIT()

 -- Example 2 --
 // Edit file group "CUSTOMER"
 DC_FILEEDIT("CUSTOMER")

 -- Example 3 --
 // Edit a file group array //
 aFileGroup := DC_FilePik()
 aFileGroup := DC_FILEEDIT( aFileGroup )

Files:

_DCFILES.PRG

See Also:

   dc_filerest()


dc_fileimp()

Import File Group(s) from the Import File Dictionary

DC_FILEIMP() is used to import file group configurations from a DXFILES.DBF file into the DCFILES.DBF file.

Syntax:

 DC_FileImp ( [<cFileGroup> | "ALL"] ) -> lStatus

Returns:

 A logical .TRUE. if the file group was imported successfully.

Arguments:

<cFileGroup> is the name of the file group.  This is a name of
up to eight (8) digits.  If a group name is passed then
the DXFILES.DBF database will be searched and all group
items that match the group name be imported into DCFILES.DBF.
If no name is passed, then a pick-list of all file groups stored
in the DXFILES.DBF database will be displayed.

If "ALL" is passed as the group name, then all groups in the
DXFILES.DBF will be imported into DCFILES.DBF.

Notes:

The DCFILES.DBF file is the data-dictionary database that contains all file group configurations. If this file does not exist in your default directory or path then it will be created. The DXFILES.DBF file is the data-dictionary database that contains all file groups that were exported from another system.

Files:

_DCFILES.PRG

See Also:

   dc_fileedit()
   dc_filerest()


dc_fileload()

Load a file group array from the file dictionary

DC_FILELOAD() is used to retrieve a file (work area) group from the DCFILES.DBF file group dictionary and store it to an array.<br><br>

Syntax:

DC_FileLoad ( [<cGroupName>], ;
              [<lCache>], ;
              [<lWorkFile>] ) -> aFileGroup

Returns:

 A file group array that conforms to the specifications in
 the RETURNS section of the function DC_FILEEDIT().

Arguments:

<cGroupName> is the name of the file group in DCFILES.DBF
to load.  If no parameter is passed, a pick-list of all
file Groups in the DCFILES.DBF dictionary will be displayed.

<lCache> if .TRUE. (default) will save the group to
a static array so the next time it is requested it will
be reloaded from the static array (cache) for faster speed.
If .FALSE. then it will not be save to the cache.

<lWorkFile> if .TRUE. will restore the file group from the
currently open database rather than the DCFILES.DBF data
dictionary.  The currently open database must have the same
structure as DCFILES.DBF.  If .FALSE.(default) then the file
group is restored from the DCFILES.DBF dictionary.

Examples:

 -- Example 1 --
 /* Restore Work areas from file dictionary */
 DC_FILELOAD( 'CUSTOMER' )

 -- Example 2 --
 /* Restore and Edit a file group array //
 cFileGroup := DC_FilePik()
 aFileGroup := DC_FILELOAD( cFileGroup )
 aFileGroup := DC_FileEdit( aFileGroup )

Files:

_DCFILES.PRG

See Also:

   dc_filerest()
   dc_fileedit()


dc_filenamedupe()

Returns the next file name in a series

DC_FileNameDupe() returns the next file name in a series so multiple files of the same name may be saved in the same directory.<br><br>This function is used when saving a file name that may already exist.<br><br>For example, if a file named C:\Download\test.prg already exists, DC_FileNameDupe( "C:\Download\test.prg" ) will return the string: "C:\Download\test (1).prg".<br><br>

Syntax:

DC_FileNameDupe( <cFileName> ) -> cNewFileName

Returns:

A character string.

Arguments:

<cFileName> is the fully-pathed file name.

Files:

_DCFUNCT.PRG, DCLIPX.DLL


dc_filepik()

Pick a file (work-area) group from the file dictionary

DC_FILEPIK() is used to pick the name of a file group from the File Group (Work Area) dictionary.<br><br><br><br>

Syntax:

DC_FilePik ( [<cTitle>] ) -> cFileGroup

Returns:

 A character string.

Arguments:

<cTitle> is the title to display on the pick-list box.

Examples:

 cFileGroup := DC_FILEPIK()
 IF !Empty(cFileGroup)
   aFileGroup := DC_FileEdit( cFileGroup )
 ENDIF

Files:

_DCFILES.PRG

See Also:

   dc_fileload()
   dc_fileedit()
   dc_filerest()


dc_filerest()

Restore work areas, indexes, relations, from dictionary

DC_FILEREST() is used to restore a complete work area environment from a the DCFILES.DBF data dictionary. This function will accomplish the following:<br><br> * Re-open all databases, using the required RDD (Replaceable Data Driver).<br><br> * Open all indexes or rebuild indexes that don't exist or have not been properly updated.<br><br> * Set parent-child relations.<br><br> * Restore record, index and tag pointers.<br><br> * Restore browse windows. (optional)<br><br> * Restore filters.<br><br> * Restore Database environment such as PATH, DEFAULT, UNIQUE, etc.<br><br>

Syntax:

DC_FileRest ( <acFileGroup>, ;
              [<lAdditive>], ;
              [<lExclusive>], ;
              [<cTagName>] ) -> lStatus

Returns:

 A file group array that conforms to the specifications in
 the RETURNS section of the function DC_FILEEDIT().

Arguments:

<acFileGroup> is the name of a file group in the DCFILES.DBF
dictionary or an array that conforms to the specifications of
the array returned by DC_FileEdit().

<lAdditive> is an optional clause which will insure that
currently used work areas are not affected.  If a database is
already opened in a work area, it will not be reopened in a new
work area.  If the <lAdditive> parameter is not passed, then
all work areas will be closed before restoring the old work.

<lExclusive> if .TRUE. will override the settings in the DCFILES.DBF
file for the file group and open the files EXCLUSIVE.  If the
parameter is not passed or is .FALSE., then files will be
opened in the default mode.

<cTagName> if passed as a character string or numeric value will
override the tag name or index order in the DCFILES.DBF file
group.

Examples:

 use maillist via 'ADSDBE"
 index on zip tag zip
 index on phone tag phones
 use customer via 'ADSDBE' new index custnmbr
 use invoice via 'ADSDBE' new index invoice
 set relation to cust_nmbr into customer
 dc_filesave( nil, nil, .t., 'MYWORK' )
 close all
 DC_FILEREST( 'MYWORK' )

Files:

_DCFILES.PRG

See Also:

   dc_fileload()
   dc_fileedit()


dc_filesave()

Save Work area definition array to dictionary

DC_FILESAVE() is used to save the contents of a file group array or the current workareas to the DCFILES.DBF data-dictionary.<br><br>

Syntax:

dc_filesave ( [<aFileGroup>], ;
              [<lWorkFile>], ;
              [<lWorkAreas>], ;
              [<cFileGroup>] ) -> lStatus

Returns:

 A logical .TRUE. if the file group was saved to the dictionary,
 .FALSE. otherwise.

Arguments:

<aFileGroup> is a file group array that conforms to the
specification of the array returned by DC_FILEEDIT().

<lWorkFile> if .TRUE. will save the file group to the
currently open database rather than the DCFILES.DBF data
dictionary.  The currently open database must be empty and
have the same structure as DCFILES.DBF.  If .FALSE. (default)
then the file group is saved to the DCFILES.DBF dictionary and
will overwrite any file group with the same name.

<lWorkAreas> if .TRUE. will save the information about
currently open workareas rather than a passed array. The
<aFileGroup> parameter is not needed and will be ignored if
<lWorkAreas> is .TRUE.  The default is .FALSE.

<cFileGroup> is needed only if <lWorkAreas> is .TRUE. This
is the name of the file group (up to 8 characters) to assign
to the file group.

Examples:

 -- Example 1 --
 /* Save Work areas to file dictionary */
 DC_FILESAVE( ,.f.,.t.,'CUSTOMER' )

 -- Example 2 --
 /* Edit and Save a file group array //
 cFileGroup := DC_FilePik()
 aFileGroup := DC_FileEdit( cFileGroup )
 DC_FILESAVE( aFileGroup )

Files:

_DCFILES.PRG

See Also:

   dc_fileload()
   dc_fileedit()
   dc_filerest()
   FILE RESTORE


dc_filock()

Lock the current file

DC_FILOCK() is used to lock the currently selected file before attempting to perform database operations that modify the data in mulitiple records.<br><br>

Syntax:

 DC_FiLock ( [<nWaitTime>], ;
             [<lDisplayError>] ) -> lStatus

Returns:

 A logical .TRUE. if the file was successfully locked.

Arguments:

<nWaitTime> is the number of seconds to wait for the system to
return a lock before returning the status or the error message.
(0 = wait forever).

<lDisplayError> if .true. will display an operator error
message if the file cannot be locked. (default) or if .false.
will not display an error message to the operator.

Examples:

 use customer
 if DC_FILOCK( 5 )
   replace print_flag with .F. for print_flag
   dc_unlock()
 endif

Files:

_DCLOCK.PRG, DCLIPX.DLL

See Also:

   dc_reclock()


dc_find()

GUI dialog for finding a record using an index

DC_FIND() is a high-level function that scans all index keys and creates an input screen to allow the user to find information by simply typing in the value in the box next to the associated index key. This is a quick method of finding information in a database that has multiple index files open or multiple index tags in a combined index.<br><br> After the user enters in the value next to the referenced index, the database is checked to see if more than one record matches the entered value. If duplicates are found, then a pick-list of records is displayed to allow the user to choose one.<br><br>

Syntax:

 DC_Find() -> lStatus

Returns:

 A logical .TRUE. if a new record was selected.

Arguments:

 None.

Examples:

 . USE EXPRESS VIA FOXCDX INDEX EXPRESS.CDX
 . DC_Find()

Files:

_DCFINDX.PRG, DCLIPX.DLL

See Also:

   dc_hunt()
   FIND


dc_findbrowse()

A browse-window find utility that uses AutoSeek

DC_FINDBROWSE() is a utility program that paints a browse with user-defined columns and a entry GET for the user to enter keyboard characters. The keys entered will automatically seek the selected index and refresh the browse. The user can click the right mouse button on a column heading to select a different index. The Up, Down, Page Up, Page Down, Ctrl Page Up, Ctrl Page Down and Enter keys are all enabled while the user is in the entry GET to allow the user to navigate the browse with keys or the mouse or enter keys for seeking.

Syntax:

 DC_FindBrowse( <aFields>, ;
                [<oParent>], ;
                [<nRow>], ;
                [<nCol>], ;
                [<nWidth>], ;
                [<nHeight>], ;
                [<cTitle>], ;
                [<lAutoSeek>], ;
                [<lHeaders>],;
                [<lPixel>], ;
                [<acbData>], ;
                [@<nPointer>], ;
                [<bEval>], ;
                [<aPres>], ;
                [<lHorizScroll>], ;
                [<lVertScroll>], ;
                [<lExit>], ;
                [<nSeekDelay>], ;
                [<cFont>], ;
                [<lLeftButtonSort>], ;
                [<bPopUp>], ;
                [<cSayIndexFont>] ) -> lStatus

Arguments:

<aFields> is a multidimensional array that defines the columns
of data to browse.

Element   Type   Description
-------   ----- ---------------------------------------------
  [1]       B    Code Block (ex: {||CUSTOMER->name})

  [2]       C    Header (ex: "Customer Name")

  [3]       N    Column Width (ex: 10)

  [4]       C    Index Name or Tag (ex: "CUSTNAME")

  [5]       C    Index Prompt (ex: "Customer Name")

  [6]      C/B   Prefix for AutoSeek

  [7]       B    Seek string code block. User input buffer
                 is passed to this code block and return
                 value of code block is used for the seek.
                 ex: {|c|Right(Space(7)+Alltrim(cString),7)}

  [8]       C    Picture clause.

Note: Only elements 1 and 2 are required.

<oParent> is the Parent window to paint the objects.  If no
parameter is passed a  modal window will be created.

<nRow> and <nCol> are the starting coordinates from the top
left of the parent window to paint the objects. These are text
based coordinates which may include decimals.  If no parent
parameter is passed, these arguments are not needed.

<nWidth> and <nHeight> are the width and height of the window
in text-based coordinates.  The defaults are 65 columns and
15 rows.

<cTitle> is the title to display in the titlebar area of the
dialog window.

<lAutoSeek> if .TRUE. (default) will include a GET for the
user to enter keys to seek automatically.  If .FALSE. then only
a browse will be displayed.  The prefix value of the selected
column is inserted before the seek string.  This may be a code
block or a string.  If it is a code block it must return a string
when evaluated.

<lHeaders> if .TRUE. (default) will display headers and a
horizontal scroll bar in the browse.  If .FALSE. no headers or
horizontal scroll bar will be displayed.

<lPixel> if .TRUE. assumes coordinates are pixel-based, otherwise
they are text-based.

<acbData> is the data source.  If it is a code block it must
return an Alias() or an array when evaluated.  If it is an alias
the database must already be opened.  If it is an array, the
array must be two-dimensional.

@<nPointer> is a numeric variable (passed by reference) to store
the array element selected when the user double-clicks on the
browse or presses ENTER.

<bEval> is a code block to evaluate after the Browse object is
created and just before invoking the event handler.  The parent
dialog object and the browse object are passed as parameters:
{|oDlg,oBrowse|...}

<aPres> is a two-element array of two subarrays.  The first
element is a Presentation Parameters array that follows the Xbase++
specification for Browse Presentation parameters.  The second
element is a two-element array :

{ aHeaderFG, aHeaderBG }

 <aHeaderFG> and <aHeaderBG> are the foreground and background
 colors of the selected column.  This is the column selected by
 the user for sorting or selecting an index.

<lHorizScroll> if .TRUE. (default) will include a horizontal
scrollbar and allow resizing of columns.

<lVertScroll> if .TRUE. (default) will include a vertical scroll
bar.

<lExit> if .TRUE. will exit without destroying the dialog window.

<nSeekDelay> is the number of seconds after a key is pressed to
wait before performing the seek.  This allows a string to be
typed without performing a seek everytime a key is pressed.
The default is .1 seconds.

<cFont> is the font compound name of the font to use for the
browse columns.

<lLeftButtonSort> if .TRUE. will allow the operator to use the
left mouse button on the column headers to select the sort order,
otherwise if .FALSE. (default), only the right button will be
enabled for sorting and the left button will allow for sizing
the columns.

<bPopUp> is a code block to evaluate.  If this variable is a
code block, a popup button will be placed to the right of the
GET used for entering a seek value.  If the user clicks on this
button or presses CTRL-ENTER while in the GET, the code block
will be evaluated.  The value in the GET is passed to the code
block and the value returned by the code block is stuffed back
into the GET.

<cSayIndexFont> is the font of the Index Name prompt to the right
of the search window.

Examples:

// Example 1 - Popup a Browse with multiple columns and AutoSeek

FUNCTION XTest()

LOCAL aFields

SET DEFA TO ..\XDOC
USE EXPRESS VIA FOXCDX EXCLUSIVE ALIAS 'XDOC'
SET INDEX TO EXPRESS.CDX
OrdSetFocus('COMMAND')
SET DEFA TO

aFields := ;
   { ; // field          Header             Width  Index       Prompt
   { {||XDOC->type},     'Type',              8,   "TYPE",     'Type' } , ;
   { {||XDOC->command},  'Command',           8,   'COMMAND',  'Command' }, ;
   { {||XDOC->category}, 'Category',          8,   'CATEGORY', 'Category' }, ;
   { {||XDOC->module},   'Module',            8,   'MODULE',   'Module' }, ;
   { {||XDOC->SHORT},    'Short Description', 25,   nil,        nil } ;
   }

DC_FindBrowse( aFields, nil, nil, nil, 85, 20, ;
    'Find Record by AutoSeek (Click Right Mouse Button in Header to change Index)' )

RETURN nil

// Example 2 - Use DC_FindBrowse() for Combo-box style picklists

LOCAL GetList := {}, cType, oType, cCommand, oCommand, cCategory, oCategory

SET DEFA TO ..\XDOC
USE EXPRESS VIA FOXCDX EXCLUSIVE ALIAS 'XDOC'
SET INDEX TO EXPRESS.CDX
OrdSetFocus('COMMAND')
SET DEFA TO

cType := Space(20)
@ 1,0 DCSAY 'Type'
@ 2,0 DCGET cType POPUP {|c|_XTest(1,oType,c)} GETSIZE 20
@ 3,0 DCSTATIC XBPSTATIC_TYPE_RECESSEDBOX SIZE 20,6 ;
   OBJECT oType EVAL {|o|o:hide()}

cCommand := Space(20)
@ 1,25 DCSAY 'Command'
@ 2,25 DCGET cCommand POPUP {|c|_XTest(2,oCommand,c)} GETSIZE 20
@ 3,25 DCSTATIC XBPSTATIC_TYPE_RECESSEDBOX SIZE 20,6 ;
   OBJECT oCommand EVAL {|o|o:hide()}

cCategory := Space(20)
@ 1,50 DCSAY 'Category'
@ 2,50 DCGET cCategory POPUP {|c|_XT est(3,oCategory,c)} GETSIZE 20
@ 3,50 DCSTATIC XBPSTATIC_TYPE_RECESSEDBOX SIZE 20,6 ;
   OBJECT oCategory EVAL {|o|o:hide()}

DCREAD GUI FIT ADDBUTTONS ;
   TITLE 'Using DC_FindBrowse() for a Database Pick-List (Pull-Down style)'

RETURN nil

/* ----------------------------- */

STATIC FUNCTION _XTest( nMode, oXbp, c )

LOCAL aFields

oXbp:show()
IF nMode = 1
  OrdSetFocus('TYPE')
  aFields := { { {||XDOC->type}, 'Type', 15, nil, nil } }
ELSEIF nMode = 2
  OrdSetFocus('COMMAND')
  aFields := { { {||XDOC->command}, 'Command', 15, nil, nil } }
ELSEIF nMode = 3
  OrdSetFocus('CATEGORY')
  aFields := { { {||XDOC->category}, 'Category', 15, nil, nil } }
ENDIF
IF DC_FindBrowse( aFields, oXbp, 0, 0, 20, 6, nil, .f., .f. )
   c := Eval(aFields[1,1])
ENDIF

oXbp:hide()

RETURN c

Files:

_DCFINDX.PRG, DCLIPX.DLL

See Also:

   dc_browseautoseek()
   @ DCFINDBROWSE
   DCFINDADDCOL
   dc_findbrowsesort()


dc_findbrowsesort()

Set Sort Header options for DC_FindBrowse()

DC_FINDBROWSESORT() is used to set the column heading options for DC_FindBrowse() when using the sort feature that is activated by clicking in the header column.<br><br>

Syntax:

 DC_FindBrowseSort( [<aSortOptions>] ) -> aOldOptions

Returns:

An array containing the old sort options.

Arguments:

<aSortOptions> is an array of 7 elements.

Element    Description
------- -------------------------------------------------------
 1 / 2  Used to set the foreground and background color of the
        column heading that is chosen as the controlling sort
        order when clicking the mouse in the column heading.
        See the SORT clause of DCBROWSECOL.

 3 / 4  Used to set the foreground and background color of the
        column headings that are not the controlling sort order.

 5 / 6  Use to set the UP arrow and DOWN arrow bitmaps that are
        used in the column header of the sorted column when
        the order is "ascending" or "descending" respectively.

 7      Used to set the color of the box drawn around the SEEK
        Get (default is GRA_CLR_RED).

Examples:

aSort := Array(6)

aSort[1] := GRA_CLR_WHITE // Sort Selected Color (Foreground)
aSort[2] := GRA_CLR_RED   // Sort Selected Color (Background)
aSort[3] := GRA_CLR_WHITE // Sort Unselected Color (Foreground)
aSort[4] := GRA_CLR_DARKGRAY // Sort Unselected Color (Background)
aSort[5] := BITMAP_RD_UP_RED  // Sort UP Bitmap
aSort[6] := BITMAP_RD_DOWN_RED  // Sort DOWN Bitmap

aSaveSort := DC_FindBrowseSort(aSort)

DC_FindBrowse( aFields, nil, nil, nil, 85, 20, ;
    'Find Record by AutoSeek (Click Right Mouse Button in Header to change Index)', ;
    nil, nil, nil, nil, nil, nil, { aPres, { GRA_CLR_DARKGRAY, GRA_CLR_RED } }, ;
    nil, nil, nil, .5 )

Files:

_DCFINDX.PRG, DCLIPX.DLL

See Also:

   dc_findbrowse()
   @ DCFINDBROWSE


dc_fontcompoundname()

Return the Font Compound name from a font object

DC_FontCompoundName() will build a string containing the Compound Name of a font from it's XbpFont() object.

Syntax:

DC_FontCompoundName( <oFont> ) -> cCompoundName

Returns:

A character string.

Arguments:

<oFont> is an XbpFont() object.

Examples:

FUNCTION XTest()

LOCAL oFont

oFont := XbpFont():new()
oFont:familyName := 'Arial'
oFont:nominalPointSize := 12
oFont:bold := .t.
oFont:italic := .t.
oFont:underScore := .t.
oFont:create()

? DC_FontCompoundName( oFont )

12.Arial Bold Italic Underscore

oFont:destroy()

RETURN nil

Files:

_DCFONT.PRG, DCLIPX.DLL

See Also:

   dc_fontconfigure()


dc_fontconfigure()

Configure a Font object from a Compound Name

DC_FontConfigure() will configure a font objects properties from a Font Compound name.

Syntax:

DC_FontConfigure( <oFont>, ;
                  <cFontCompoundName>, ;
                  [<nCodePage>] ) -> oFont

Returns:

The configured font object.

Arguments:

<oFont> is an XbpFont() object.

<cFontCompoundName> is a character string containing the
compound name of the font.

Examples:

11.Arial
12.Courier New
14.Courier New Bold
20.Lucida Console Italic Underscore

<nCodePage> is the optional code page of the font to select.

Examples:

oFont := GraSetFont(oPS)
cSaveFont := DC_FontCompoundName(oFont))
DC_FontConfigure(oFont,'12.Arial Underscore')
GraSetFont(oPS,oFont)
GraStringAt('This is some text in "12.Arial Underscore" font')
DC_FontConfigure(oFont,cSaveFont)
GraSetFont(oPS,oFont)

Files:

_DCFONT.PRG, DCLIPX.DLl

See Also:

   dc_fontcompoundname()


dc_formatmemotowidth()

Format a memo to fit within a specified area

DC_FormatMemoToWidth() is used to create a memo that fits perfectly within a specified area based on the font used. CR characters will be removed and reinserted in the location required to format each line to the desired width.<br><br><br><br>

Syntax:

DC_FormatMemoToWidth( <cString>, ;
                      <nWidth>, ;
                      <oPS | cFont> ) -> cString

Returns:

A character string.

Arguments:

<cString> is the memo to format.

<nWidth> is the width, in pixels.

<oPS> is the presentation space object that contains the font,
or alternately <cFont> is the font compound name.

Examples:

Run XDEMO.EXE - Sample Group 6 - Memo Format

Files:

_DCFUNCT.PRG, DCLIPX.LIB, DCLIPX.DLL


dc_fornext()

Evaluate a list of expressions in a FOR..NEXT loop

DC_FORNEXT() is a "function" replacement for FOR...NEXT loops to be used when a function is needed, i.e. for calling via macro, code blocks, etc.<br><br><br><br><br><br>

Syntax:

 DC_ForNext ( <nStart>, ;
              <nEnd>, ;
             [<nStep>], ;
              <bEval>, ;
             [<bWhile>] ) -> NIL

Returns:

 Nil.

Arguments:

<nStart> is the starting value to be assigned to a variable
which will be incremented for each iteration of a FOR...NEXT
loop.

<nEnd> is the ending value.

The incremental value will be passed to the <bEval> code block
for each iteration of the loop.

<nStep> is the incremental value.  The default is 1.

<bEval> is a code block to evaluate for each iteration of the
loop.

<bWhile> is an code block which must evaluate to .true. to
continue the loop, otherwise the loop will be terminated.

Examples:

 bEval := { | x | qout(x, sqrt(x) ) }
 bWhile := { || inkey()#27 }
 DC_FORNEXT( 100, 1000, 5, bEval, bWhile )

Files:

_DCEVAL.PRG, DCLIP1.DLL

See Also:

   dc_ifelse()
   dc_docase()
   dc_dowhile()


dc_getactive()

Return the currently active GET object

DC_GETACTIVE() is an environment function that provides access to the active GET object during a READ. The current active Get object is the one with input focus at the time DC_GETACTIVE() is called.

Syntax:

DC_GetActive () -> oGet

Returns:

 DC_GETACTIVE() returns the current active Get object within the
 current READ by DC_READMODAL().  If there is no READ active when
 DC_GETACTIVE() is called, it returns NIL.

Arguments:

 NONE

Notes:

DC_GETACTIVE() works with DC_READMODAL() in the same way that Clipper's GETACTIVE() works with READMODAL().

Examples:

 // This code uses a WHEN clause to force control to branch to a
 // special reader function.  Within this function, DC_GETACTIVE()
 // retrieves the active Get object:

 GetList := {}
 @ 10, 10 GET x
 @ 11, 10 GET y WHEN MyReader()
 @ 12, 10 GET z
 dc_readmodal( GetList )

 // Called just before second get (above)
 // becomes current
 FUNCTION MyReader
 LOCAL objGet               // Active Get holder
 objGet := DC_GETACTIVE()      // Retrieve current
                               // active Get
 BarCodeRead( objGet )
 RETURN (.F.)               // Causes Get to be
                            // skipped in READ

Files:

_DCGETSY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()


dc_getactiveinfo()

Return the currently active GET object

DC_GETACTIVEINFO() is an environment function that provides access to the active dialog object during a READ GUI. The current active object is the one with input focus at the time DC_GETACTIVEINFO() is called.

Syntax:

 DC_GetActiveInfo( [<oXbp>] ) -> aInfo

Returns:

 A single dimensional array of 4 elements:

 Element  Type   Description
 -------  ----   ----------------------------------------
  [1]      C     Variable name associated with object
  [2]      C     Procedure name that object was defined
  [3]      N     Procedure line that object was defined
  [4]      O     A pointer to the object

Arguments:

<oXbp> is a pointer to any object.  If this parameter is not
passed or is not an object, then the object in focus is the
default.

Notes:

DC_GETACTIVEINFO() works with DC_READGUI() in a similar way to the way Xbase++ GETACTIVE() works with READMODAL().

Examples:

 . STORE Space(10) TO cGet1, cGet2, cMemo1
 . @ 1,1 DCSAY 'Get 1' GET cGet1
 . @ 2,1 DCSAY 'Get 2' GET cGet2
 . @ 4,1 DCMULTILINE cMemo1 SIZE 30,10
 . DCHOTKEY xbeK_ALT_I ACTION {||DC_MsgBox(DC_GetActiveInfo()}
 . DCREAD GUI FIT ADDBUTTONS

Files:

_DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readgui()


dc_getanchorcb()

Create a codeblock to anchor local variables to the GetList

DC_GETANCHORCB() is used to create a code-block that will anchor a local variable to a GetList array. This allows a reference to a local variable to be passed to a text or GUI reader via a GetList array to be used as a :dataLink for Xbase Parts.<br><br>

Syntax:

DC_GetAnchorCB ( <uVar>, ;
                 [<cType>], ;
                 [<xValue>], ;
                 [<cPicture>] ) -> bAnchor

Returns:

 A Code Block.

Arguments:

<uVar> is the local variable.  IF neither the <cType> or
<xValue> parameters are used, then the code block converts
a character string to the type of the variable.  This is
needed by the GUI get system because XbpGet() objects can
only work with character strings.

<cType> is the type of value the codeblock is expecting
when it is evaluated.

<xValue> is the value of the variable to return when the
code block is evaluated.

<cPicture> is an optional picture clause to use with
numeric or date variables.

Examples:

 #command GET <uVar> =>  ;
     AAdd( myGetlist, DC_GETANCHORCB(@<uVar>) )

 #command GET <uVar> PICT <cPict> => ;
     AAdd( myGetlist, DC_GETANCHORCB(@<uVar>,,,<cPict>)

 #command CHECKBOX <lVar> => ;
     AAdd( myGetlist, DC_GETANCHORCB(@<uVar>,'L')

Files:

_DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readgui()


dc_getbitmap()

Create a bitmap object from any source

DC_GetBitMap() returns an XbpBitMap() object from a variety of input sources.<br><br>

Syntax:

DC_GetBitMap( <xBitMap>, ;
              [<nType>], ;
              [<cResType>], ;
              [<cResFile>], ;
              [<anScale>], ;
              [<aAllowIcons>], ;
              [<aSize>] ) -> xBitMap

Returns:

An XbpBitMap() object.

Arguments:

<xBitMap> is any of the following variable types:

C - Character.  This is a string that may contain a file name.
The contents of the string is tested to see if it contains a
valid .BMP, .JPG or .GIF file.  If it does and the file exists,
it is loaded to an XbpBitMap() object and the object is returned.
If it is not a valid .BMP, .JPG or .GIF file, the original string
passed in (<xBitMap>) is returned.

N - Numeric.  This is a numeric resource that has been linked
into the executable program.  It is tested to insure that it is
a valid bitmap resource and then is converted to an XbpBitMap()
object.  If it is not a valid bitmap resource or <nType> is
anything other than 0 or XBPSTATIC_TYPE_BITMAP (defined in XBP.CH)
then the original numeric value passed in (<xBitMap>) is returned.

O - Object.  If <xBitMap> is an XbpBitMap() object, it is returned
without being modified.

B - Code Block.  If <xBitMap> is a code block, then the code block
will be evaluated.  The return value must be an objec of the
XbpBitmap() class.

<cResType> provides support for bitmap resources of type
BMP, PNG, GIF and JPEG that have been linked into a .RES file to
be used as the caption.

Example:

<cResType> = 'GIF'

// myres.arc
USERDEF GIF
2000 = FILE ".\GIFChart.GIF"

<cResFile> is the name of the .DLL that contains the resource
stated in the RESTYPE <cResType> clause.  If this parameter
is not used, then the resource must be in the .EXE.

If <anScale> is a numeric value, then <anScale> is the scaling
factor to use for the new bitmap, based on the original bitmap
size.  For example, if the original bitmap size is 25x25 pixels
and <anScale> is 2, then the new bitmap size is 50x50 pixels.

If <anScale> is an array, then it must contain 2 numeric elements,
the new X size and the new Y size of the bitmap.

Note: For <anScale> to produce a bitmap with a proper color
palette, it is recommended that the original bitmap be created
using a 24-bit palette.

<lAllowIcons>, if .T. will return an XbpIcon() object instead
of an XbpBitmap() object if xBitmap is an icon resource.  The
default is .F.

<aSize> is a 2-dimensional array of 2 numeric values that will
set the size of the icon, if <lAllowIcons> is .T.  If <aSize>
is not used, then the size will be determined by the original
resource size.

Notes:

If DC_BitMapTransparentColor() has been set to a value, it willbe applied to the XbpBitMap() object that is returned.

Examples:

DC_BitmapTransparentColor({192,192,192})

@ 137,275 DCSTATIC XBPSTATIC_TYPE_BITMAP OBJECT oRedFlag ;
          ID "RedFlag" SIZE 19,19 PIXEL ;
          TOOLTIP {||IIF(empty(dc_getcargo(oRedFlag)),   ;
                 "No Flags","Flags exist: "+dc_getcargo(oRedFlag))};
          CAPTION {||IIF(empty(aName[cnAlerts]),;
                     DC_GetBitMap(BITMAP_FLAG_2),;
                     DC_GetBitMap(BITMAP_FLAG_1))}

Files:

_DCGETBX.PRG

See Also:

   dc_bitmaptransparentcolor()


dc_getbrowarray()

Get or Store an array pointer from/to Array Browse

DC_GetBrowArray() is used to store a new array pointer to an existing array browser when using DCBROWSE to browse an array.

Syntax:

 DC_GetBrowArray( <oBrowse>, ;
                  [<aArray>] ) -> aArray

Returns:

 A pointer to the current array being browsed.

Arguments:

<oBrowse> is a pointer to the browse object created by the
DCBROWSE command.

<aArray> is a pointer to the new array to browse.

Examples:

FUNCTION XTest()

LOCAL GetList := {}, aDirectory, aFiles, oBrowDirs, oBrowFiles, ;
      nPointer := 1, bItemMarked

aDirectory := Directory('*.','D')
aFiles := {}
_Files( aDirectory, aFiles, 1 )
bItemMarked := {||_Files(aDirectory,aFiles,nPointer,oBrowFiles)}

@ 0,0 DCBROWSE oBrowDirs DATA aDirectory SIZE 30,10 ;
      EVAL {|o|o:itemMarked := DC_MergeBlocks(o:itemMarked,bItemMarked) } ;
      POINTER nPointer ;
      PRESENTATION DC_BrowPres()

DCBROWSECOL DATA {||DC_GetColArray(nil,oBrowDirs)[1]} ;
   HEADER 'Directory' WIDTH 20 PARENT oBrowDirs

@ 0,35 DCBROWSE oBrowFiles DATA aFiles SIZE 30,10 ;
       PRESENTATION DC_BrowPres()

DCBROWSECOL ELEMENT 1 HEADER 'File Name' WIDTH 20 PARENT oBrowFiles

DCREAD GUI FIT ADDBUTTONS TITLE 'One-to-Many Directory Browse'

RETURN nil

* -------------------

STATIC FUNCTION _Files( aDirectory, aFiles, nPointer, oBrowFiles )

LOCAL i, cDirectory, cCurPath := DC_CurPath()

cDirectory := aDirectory[nPointer,1]
DC_ChDir( cDirectory )

aFiles := Directory( '*.*')
DC_ChDir( cCurPath )

IF Valtype(oBrowFiles) = 'O'
  DC_GetBrowArray( oBrowFiles, aFiles )
  oBrowFiles:refreshAll()
ENDIF

RETURN nil

Files:

_DCGETBX.PRG, DCLIPX.DLL

See Also:

   DCBROWSE
   dc_getcolarray()


dc_getcargo()

Get and/or set the cargo of an object

DC_GETCARGO() is used to store any type of variable in the :cargo container of objects created by DC* commands.

Syntax:

DC_GetCargo ( <oXbp>, ;
              [<xCargo>] ) -> xOldCargo

Returns:

 The previously store cargo variable.

Arguments:

<oXbp> is any object created by a DC* command.

<xCargo> is a variable of any type including multidimensional
array or code block.

Notes:

All DC* commands use the :cargo container of Xbp*() objects for miscellaneous data required for eXPress++ functions. This cargo is always an array of at least 3 elements with element #3 reserved for user cargo. DC_GetCargo() is a handy function that stores and/or retrieves data from this element.

Examples:

 // Store the directory into the DCPUSHBUTTON identifed by
 // it's ID clause as 'OK_BUTTON'

 DC_GetCargo( DC_GetObject(GetList,'OK_BUTTON'), Directory() )

 // Return the cargo

 aDirectory := DC_GetCargo( DC_GetObject(GetList,'OK_BUTTON') )

Files:

_DCGETBX.PRG/.OBJ, DCLIPX.LIB


dc_getcolarray()

Get Column array information from a DCBROWSE array browse

DC_GetColArray() returns information about the currently selected array element of a DCBROWSE object when browsing an array.<br><br> This function is necessary when browsing an array and the information in a column must be specially formatted in a code block.<br><br>

Syntax:

 DC_GetColArray( [<nElement>], ;
                  <oBrowse>, ;
                  <xValue> ) -> xInfo

Arguments:

If <nElement> is a NIL, then the entire sub-array is returned.
If <nElement> is a 0, then the numeric value of the sub-array
is returned, ie the number of the currently selected sub-array
element.  If <nElement> is a 1 or more, then the contents of
the currently selected sub-array, element <nElement> is returned.

<oBrowse> is a pointer to the Browse object.

IF <xValue> is passed, then <nElement> must be a 1 or greater.
The element <nElement> of the selected sub-array will be assigned
the value of <xValue>.

Examples:

FUNCTION XTest()

/*  ARRAY BROWSER WITH COLORS

 This example demonstrates how to control the color of cells in
 an array browser using DCBROWSE.  In this example, the color of
 the SIZE cells is dependent on the size of the file.  The
 function DC_GETCOLARRAY() is used as a pointer into the array
 being browsed.

*/

LOCAL GetList := {}, cFileName, oFileName, oDirGroup, aDirectory, i, ;
      aFile, oDirectory, aColors, bColor

cFileName := Space(30)

@ 2,2 DCGET cFileName GETSIZE 43 GETOBJECT oFileName

@ 3.5,2 DCSTATIC XBPSTATIC_TYPE_RECESSEDBOX SIZE 43,13 ;
      OBJECT oDirGroup

aDirectory := Directory()
FOR i := 1 TO Len(aDirectory)
  ASize(aDirectory[i],5)
  aDirectory[i,5] := .f.
NEXT
aFile := aDirectory[1]

@ 2,2 DCBROWSE oDirectory PARENT oDirGroup DATA aDirectory ;
      SIZE 297,253 PIXEL ;
      FONT '10.Helv.Bold' ;
      INTO aFile ;
      DATALINK {||cFileName:=aFile[1],oFileName:SetData()} ;
      MARK 5 ;
      MKCOLOR 5, GRA_CLR_WHITE, GRA_CLR_BLUE

aColors := { {GRA_CLR_WHITE,GRA_CLR_DARKRED}, ;
             {GRA_CLR_WHITE,GRA_CLR_DARKBLUE}, ;
             {GRA_CLR_BLACK,GRA_CLR_DARKGREEN}, ;
             {GRA_CLR_BLACK,GRA_CLR_YELLOW} }

bColor := {| nSize, nCase | nSize := DC_GetColArray(2,oDirectory),;
              nCase := DC_PickCase(nSize,'>=',;
                          {1000000,100000,10000,0}, ;
                          {      1,     2,    3,4} ), aColors[nCase] }

DCBROWSECOL ELEMENT 1 WIDTH 8 HEADER "Name" PARENT oDirectory

DCBROWSECOL ELEMENT 2 WIDTH 5 HEADER "Size" PARENT oDirectory ;
  EVAL { |o|o:colorBlock := bColor }

DCBROWSECOL ELEMENT 3 WIDTH 5 HEADER "Date" PARENT oDirectory

DCBROWSECOL ELEMENT 4 WIDTH 5 HEADER "Time" PARENT oDirectory

DCBROWSECOL ELEMENT 5 WIDTH 4 HEADER "Marked" PARENT oDirectory

DCREAD GUI ;
   FIT ;
   MODAL ;
   BUTTONS DCGUI_BUTTON_OK + DCGUI_BUTTON_CANCEL ;
   TITLE 'Array Browse of Directory'

RETURN nil

Files:

_DCGETBX.PRG, DCLIPX.DLL

See Also:

   @ DCBROWSE
   DCBROWSECOL
   dc_getbrowarray()
   dc_browserow()


dc_getcomboimmediate()

Changes behavior of @ DCGET .. COMBO

DC_GetComboImmediate() is a Get/Set function that changes the behavior of @..DCGET..COMBO. A .TRUE. setting will cause the GET to update every time a new item is selected in the dropdown browse. A .FALSE. setting will cause the GET to update only after double-clicking in the browse.

Syntax:

DC_GetComboImmediate( <lSet> ) -> lPreviousSetting

Returns:

A logical value.

Arguments:

<lSet> is a logical value.

Files:

_DCCLASS.PRG, DCLIPX.DLL

See Also:

   @ DCGET


dc_getcombomode()

Set mouse mode for @..DCGET..COMBO

DC_GetComboMode() is used to set the mouse click mode for dropdown windows of the @..DCGET..COMBO or @..DCSAY..GET..COMBO command. <br><br>

Syntax:

DC_GetComboMode( [<nMode>] ) -> nOldMode

Returns:

The previous mode setting.

Arguments:

<nMode> is a numeric value from the below table:

* - Default

 nMode  Description
 ----- ----------------------------------------------------
   0 *  A double click of the mouse selects the item from the
        dropdown picklist.

   1    A single click of the mouse selects the item from the
        dropdown picklist.

Files:

_dcfindx.prg, dclipx.dll

See Also:

   @ DCSAY
   @ DCGET


dc_getdestroy()

Destroy all objects in the Dialog Getlist

DC_GETDESTROY() is used to destroy all objects in the Get List. This function is needed to destroy objects that were added to a parent dialog system by DC_READGUI() without destroying any current objects in the parent dialog.<br><br><br><br>

Syntax:

DC_GetDestroy ( <aGetList>, ;
                [<acoGroup>], ;
                [<lRemove>], ;
                [<lChildrenOnly>] ) -> nil

Returns:

 A logical value.

Arguments:

<aGetList> is an array containing a list of Get objects to
destroy.  The GetList must a Gui-based Get List compatible
with DC_ReadGets() or DC_ReadGui().

<acoGroup> is the GetList group or parent object to destroy.
Each item in the GetList may be assigned a group name via the
GROUP <acGroup> clause.  If a character value is passed, then
only the items in the GetList which match <acoGroup> will be
destroyed.  <acoGroup> may consist of an array of character
values so that more than one group may be destroyed. If
<acoGroup> is a NIL then all items in the GetList will be
destroyed.  If <acoGroup> is an object pointer, then all
children items of the object will be destroyed.

<lRemove> if .TRUE. will not only destroy objects, but will also
remove them from the GetList.

<lChildrenOnly> if .TRUE. will remove only the Child objects
(and their children), of the parent object and not remove the
parent object.

Examples:

 -- Example 1 --

 See XSample_144() in XSAMPLE5.PRG for an example using
 DC_GetDestroy() in conjunction with DC_MergeGetLists().

 -- Example 2 --

 #include 'dcdialog.ch'

 PROCEDURE XTest()

 LOCAL GetList := {}, GetOptions, cFirst := Space(10), ;
       cLast := Space(10), cPhone := Space(15), oFirst, oDlg, ;
       oPhoneButton

 @ 0,0 DCSAY ' Last Name' GET cLast
 @ 2,0 DCSAY 'First Name' GET cFirst SAYOBJECT oFirst

 @ 7,0 DCPUSHBUTTON CAPTION 'Phone' ;
   OBJECT oPhoneButton ;
   SIZE 8,1.5 ;
   ACTION {||_GetPhone(oDlg,@cPhone,oFirst,oPhoneButton)}

 DCREAD GUI ;
   FIT ;
   PARENT @oDlg ;
   ADDBUTTONS

 RETURN

 /* --------------------- */

 STATIC FUNCTION _GetPhone( oDlg, cPhone, oFirst, oPhoneButton )

 LOCAL GetList := {}

 @ 2,0 DCSAY " Phone Num" GET cPhone RELATIVE oFirst ;
   PARENT oDlg PICT '999-999-9999'

 @ 0,10 DCPUSHBUTTON CAPTION 'Done' ;
   RELATIVE oPhoneButton ;
   SIZE 8,1.5 ;
   ACTION {||DC_GETDESTROY(GetList)}

 DCREAD GUI PARENT oDlg EXIT SAVE

 RETURN nil

Files:

_DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readgui()


dc_getdevout()

A Replacement for DevPos()/DevOut() when writing @SAY..GETS

DC_GETDEVOUT() is used in @SAY..GET translations contained in DCGET.CH in place of DevPos() and DevOut(). This function will not display the prompt on the screen if it has been positioned outside the scroll-region coordinates pre-set by DC_READBOX() or DC_READWINDOW() and will set appropriate static flags for DC_READMODAL() to allow for scrolling the prompt in the GET window area.<br><br>

Syntax:

DC_GetDevOut ( <nRow>, ;
               <nCol>, ;
               <cExpr>, ;
               <cColor> ) -> nil

Returns:

 Nil

Arguments:

<nRow> is the display row.

<nCol> is the display column.

<cExpr> is the string to display.

<cColor> is the display color for the string.  If no argument
is passed, the current system color will be used.

Notes:

DC_READWINDOW() or DC_READBOX() must be called before displaying any SAYS with the @SAY..GET command or with DC_GETDEVOUT().

Examples:

 #include "dcget.ch"

 LOCAL GetList := {}, aData, i

 use <cDataFile>
 aData := Array(Fcount())
 FOR i := 1 TO LEN( aData )
   aData[i] := FieldGet(i)
 NEXT
 DC_ReadWindow( { 10, 10, 20, 60 } )
 FOR i := 1 TO LEN(aData)
   DC_GETDEVOUT( i, 12, PadL(Field(i),10), )
   SetPos( Row(), Col()+1 )
   AAdd( GetList,_GET_(aData[i],"aData[i]",,,) )
   DC_GetDisplay( GetList )
   GetList := DC_AddCargo(GetList,-1*i)
   GetList := ;
      DC_AddCargo(GetList,{ 108, { i, 12, PadL(Field(i),10) }})
 NEXT
 DC_ReadModal( GetList,,aReadArea )
 RETURN nil

Files:

_DCGETSY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()
   dc_readbox()


dc_getdisplay()

Display a GET on the screen if it falls in scroll region

DC_GETDISPLAY() is used in @SAY..GET translations contained in DCGET.CH in place of the default display method. This function will not display the GET on the screen if it has been positioned outside the scroll-region coordinates pre-set by DC_READBOX() or DC_READWINDOW() and will set appropriate static flags for DC_READMODAL() to allow for scrolling the GET in the pre-established window area.<br><br>

Syntax:

DC_GetDisplay ( <GetList> ) -> nil

Returns:

 Nil

Arguments:

<GetList> is the GET array containing a set of GETS.

Notes:

DC_READWINDOW() or DC_READBOX() must be called before displaying any GETS with the @SAY..GET command or with DC_GETDISPLAY().

Examples:

 #include "dcget.ch"

 LOCAL GetList := {}, aData, i

 use <cDataFile>
 aData := Array(Fcount())
 FOR i := 1 TO LEN( aData )
   aData[i] := FieldGet(i)
 NEXT
 DC_ReadWindow( { 10, 10, 20, 60 } )
 FOR i := 1 TO LEN(aData)
   DC_GetDevOut( i, 12, PadL(Field(i),10), )
   SetPos( Row(), Col()+1 )
   AAdd( GetList,_GET_(aData[i],"aData[i]",,,) )
   DC_GETDISPLAY( GetList )
   GetList := DC_AddCargo(GetList,-1*i)
   GetList := ;
      DC_AddCargo(GetList,{ 108, { i, 12, PadL(Field(i),10) }})
 NEXT
 DC_ReadModal( GetList,,aReadArea )
 RETURN nil

Files:

_DCGETSY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()
   dc_readbox()


dc_gethelpcode()

Return the Help Code of an object

DC_GETHELPCODE() is used to return the Help Code from the GetList that is associated with a specified object. Help Codes are associated with objects created by DC* commands by using the HELPCODE <cHelpCode> clause of the command. Context-Sensitive Help systems require that when a Help Request for an object does not return a Help Code (because one has not been assigned), then the help code of the parent of that object should be returned. DC_GetHelpCode() walks up the tree until it finds a Help Code. If no Help Code is found then the returned value is a NIL.<br><br> <br><br>

Syntax:

DC_GetHelpCode ( <oXbp>, ;
                 [@<aGetList>], ;
                 [@<aGetListItem>] ) -> cHelpCode

Returns:

A Character String.

Arguments:

<oXbp> is a pointer to any object that was created by DC_ReadGui().

@<aGetList> is a variable, passed by reference, to store a pointer
to the GetList that is associated with the object.

@<aGetListItem> is a variable, passed by reference, to store a
pointer to the GetList Item that is associated with the object.

Examples:

 -- Example 1 --

 #include 'dcdialog.ch'

 PROCEDURE XTest()

 LOCAL oStatic, oDate, dDate := Date()

 @ 1,1 DCSTATIC TYPE XBPSTATIC_TYPE_RECESSEDBOX SIZE 30,5 ;
       OBJECT oStatic HELPCODE 'MYAPP.STATIC'

 @ 2,2 DCSAY 'Date' GET dDate GETOBJECT oDate

 @ 7,1 DCPUSHBUTTON CAPTION 'Get Help' SIZE 10 ;
       ACTION {||DC_DebugQout({DC_GetHelpCode(oDate)})}

 DCREAD GUI FIT

 RETURN nil

Files:

_DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_getproperty()


dc_gethotkeylist()

Retrieve a list of hotkeys that have been set

DC_GETHOTKEYLIST() is used to return an array of HotKeys that have been set either by using the DCHOTKEY command, the ACCELKEY clause of DC* commands or the SetKey() function.<br><br>

Syntax:

DC_GetHotKeyList( [<aGetList>] ) -> aHotKeys

Returns:

 An array with information about the Hotkeys.  Each element of
 the array contains 3 sub-elements:

 Element  Type  Description
 -------  ----- ------------------------------------------
    1       C   The character-string definition of the hotkey
    2       N   The numeric value of the hotkey
    3       B   Tha action code block associated with the hotkey

Arguments:

<aGetList> is the GetList for the dialog window which contains
DCHOTKEY commands or ACCELKEY clauses of DC* commands.  If
<aGetList> is not passed then an array of information about
hotkeys created with the SetKey() function is returned.

Examples:

#include "dcdialog.ch"
#include "appevent.ch"
#include "inkey.ch"

-- Example 1 --

FUNCTION XTest()

LOCAL GetList[0]

@ 1,1 DCPUSHBUTTON CAPTION 'Test' ACTION {||MsgBox('test T')} ;
      ACCELKEY xbeK_ALT_T

DCHOTKEY xbeK_ALT_Z ACTION {||MsgBox('test Z')}

DCREAD GUI FIT SAVE

DC_ArrayView( DC_GetHotKeyList(GetList) )

RETURN nil

-- Example 2 --

FUNCTION XTest()

SetKey(K_ALT_T,{||MsgBox('test T')})
SetKEy(K_ALT_Z,{||MsgBox('text Z')})

DC_ArrayView( DC_GetHotKeyList() }

RETURN nil

Files:

_DCPUTK.PRG/.OBJ, DCLIPX.LIB


dc_getiddefault()

Assign a default ID based on field/memvar name

DC_GetIDDefault() will return an ID for an object based on the name of the variable passed. It is used in DCDIALOG.CH to automatically assign a default ID when getting data that is an aliased field.<br><br>Example 1 : @..DCGET MYFILE->name<br><br>This will assign an ID of GET_MYFILE_NAME<br><br>Example 2 : DCBROWSECOL FIELD MYFILE->name<br><br>This will assign an ID of COL_MYFILE_NAME

Syntax:

DC_GetIDDefault( [<cId>], ;
                 [<cVarName>], ;
                 [<cPrefix<] ) -> cId

Arguments:

<cId> if not empty will be returned as the return value.

<cVarName> if empty will return <cId>.
<cVarName> if not empty must include an alias -> pointer.
example: "MYFILE->MYFIELD"

<cPrefix> is the prefix to put on the returned value.

Examples:

DC_GetIDDefault( nil, 'MYFILE->MYFIELD', 'GET_' )

Returns: GET_MYFILE_MYFIELD

Files:

DCLIPX.LIB, DCLIPX.DLL, DCDIALOG.CH


dc_getlistobject()

Return a pointer to the DC_GetList() object from a GetList Array

DC_GetListObject() is used to return a pointer to the DC_GetList() object.<br><br>

Syntax:

DC_GetListObject( aGetList ) -> oGetList

Returns:

An object of the class DC_GetList.

Arguments:

<aGetList> is a GetList array.

Notes:

The GetList array must first have been passed to the DCREAD GUIcommand.

Examples:

#include "dcdialog.ch"

FUNCTION Main()

LOCAL GetList[0]

@ 0,0 DCSAY 'Testing'

DCREAD GUI FIT TITLE 'Testing' EVAL {||ShowTitle(GetList)}

RETURN nil

* -----------

STATIC FUNCTION ShowTitle( GetList )

LOCAL oGetList

oGetList := DC_GetListObject( GetList )

DCMSGBOX oGetList:parentDlg:title

RETURN nil

Files:

_DCGETBX.PRG, DCLIPX.DLL


dc_getlisttype()

Return the "define" name of a Get Object from it's type

DC_GETLISTTYPE() is a handy debugging function to determine the manifest name of the defined "type" of object.<br><br>

Syntax:

DC_GetListType ( <nType> ) -> cType

Returns:

 A Character String.

Arguments:

<nType> is the numeric value stored in element nGETLIST_TYPE
of each Getlist array object.

Examples:

 #include "dcdialog.ch"
 #include "xbp.ch"

 FUNCTION XDemo_1 ()

 LOCAL GetList := {}, GetOptions, oTabPage1, oTabPage2, oTabPage3,;
       cPlayer, cTeam, cLeague, cPosition, cMemo, dDateAcq,;
       nOrigPrice, nPresValue, nCardNmbr, nYear, cComments, ;
       aLeague, aTeam, aPosition

 aLeague := { 'NL','AL','BL','BS' }

 aTeam   := { 'Dodgers','Yankees','Reds','Cardinals','Giants',;
              'Twins','Red Sox','White Sox' }

 aPosition := { '1B','2B','3B','SS','P','C','LF','CF','RF','DH' }

 /* ---- Tab Page #1 ---- */

 @  3,3,15,62 DCTABPAGE oTabPage1 CAPTION 'Player Data'

 @  3,2  DCSAY "Player Name" GET cPlayer SAYRIGHT PARENT
         oTabPage1 SAYSIZE 10

 @  5,2  DCSAY "Team" SAYRIGHT PARENT oTabPage1 SAYSIZE 8

 @  5,11 DCCOMBOBOX cTeam LIST aTeam SIZE 10,6 PARENT oTabPage1

 @  5,23 DCSAY "Position" SAYRIGHT PARENT oTabPage1 SAYSIZE 8

 @  5,33 DCCOMBOBOX cPosition LIST aPosition SIZE 6,6 PARENT ;
    oTabPage1

 @  5,40 DCSAY "League" SAYRIGHT PARENT oTabPage1 SAYSIZE 8

 @  5,50 DCCOMBOBOX cLeague LIST aLeague SIZE 4,4 ;
    PARENT oTabPage1

 DCGETOPTIONS WINDOW HEIGHT 400 ;
               WINDOW WIDTH 500 ;
               SAYWIDTH 100

 /* ---- See output below ---- */
 FOR i := 1 TO LEN(GetList)
   ? i, DC_GETLISTTYPE( GetList[i,nGETLIST_TYPE] )
 NEXT

 DC_ReadGui( GetList, 'My BASEBALL CARD Inventory', ;
             GetOptions, .t. )

 RETURN nil

 /* ------------------- */

 Output Screen:

       1 GETLIST_TABPAGE
       2 GETLIST_SAY
       3 GETLIST_GET
       4 GETLIST_SAY
       5 GETLIST_COMBOBOX
       6 GETLIST_SAY
       7 GETLIST_COMBOBOX
       8 GETLIST_SAY
       9 GETLIST_COMBOBOX

Files:

_DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readgets()


dc_getlistvalidate()

Validate all objects in GetList

DC_GETLISTVALIDATE() is used to test all VALID clauses in the GetList and set focus to the first object that fails validation.

Syntax:

 DC_GetListValidate( <aGetList> ) -> lStatus

Arguments:

<aGetList> is a valid GetList array.

Examples:

#include 'dcdialog.ch'

FUNCTION XTest()

LOCAL GetList := {}, cFrom := Space(8), cTo := Space(8), ;
      dFrom := CTOD('  /  /    '), dTo := CTOD('  /  /    ')

SET DATE FORMAT TO 'mm/dd/yyyy'

@ 1,0 DCSAY 'From Time:' ;
   GET cFrom ;
   PICTURE '99:99:99' ;
   VALID {|| IIF(!EMPTY(Strtran(cFrom,':','')), .T., ;
             (DC_MsgBox({'From Time cannot be empty.'}), .F.))}

@ 2,0 DCSAY '  To Time:' ;
   GET cTo ;
   PICTURE '99:99:99' ;
   VALID {|| IIF(!EMPTY(StrTran(cTo,':','')), .T., ;
             (DC_MsgBox({'To Time cannot be empty.'}), .F.))}

@ 3,0 DCSAY 'From Date:' ;
   GET dFrom ;
   PICTURE '@D' ;
   VALID {|| IIF(!EMPTY(dFrom), .T., ;
             (DC_MsgBox({'From Date cannot be empty.'}), .F.))}

@ 4,0 DCSAY '  To Date:' ;
   GET dTo ;
   PICTURE '@D' ;
   VALID {|| IIF(!EMPTY(dTo), .T., ;
             (DC_MsgBox({'To Date cannot be empty.'}), .F.))}

@ 6,0 DCPUSHBUTTON CAPTION 'Validate' SIZE 10,2 ;
      ACTION {||DC_GetListValidate(GetList)}

DCREAD GUI FIT ADDBUTTONS

RETURN nil

Files:

_DCGETBX.PRG, DCLIPX.DLL

See Also:

   dc_getvalidate()
   DCGETOPTIONS


dc_getnetname()

Returns the Network name of the workstation

DC_GetNetName() returns the Network name of the current workstation.

Syntax:

DC_GetNetName() -> cNetName

Returns:

A character string.

Arguments:

None.

Files:

_DCFUNCT.PRG, DCLIPX.DLL


dc_getobject()

Return a pointer to an object from an ID name

DC_GETOBJECT() is used to return a pointer to the actual object from a GetList ID tag.<br><br> This function will scan the GetList array for the GetList item which matches the character string ID which was assigned to the GetList object. An ID is assigned via the ID <id> clause for each GetList command. This function eliminates the need to assign a memory variable to an object to get a reference to the object.<br><br>

Syntax:

DC_GetObject ( <aGetList>, ;
               <cID> ) -> oObject

Returns:

 A Pointer to the object created by DC_ReadGui() for the item
 in the GetList that matches <cId>.  IF <cId> is not found in the
 Getlist, then a NIL is returned.

Arguments:

<aGetList> is an array containing a list of Get objects to
refresh.  The GetList may be Dual-Mode Getlist compatible
with DC_ReadGets() or DC_ReadGui() or a text-based GetList
compatible with DC_ReadModal().

<cID> is a character string equivalent to the ID assigned to the
item in the GetList.  This is case-sensitive.

Notes:

Examples:

 -- Example 1 --

 #include 'dcdialog.ch'

 PROCEDURE XTest()

 #define cDesc      aLocals[1]
 #define cType      aLocals[2]
 #define cSubType   aLocals[3]
 #define oToolBar   aLocals[4]

 LOCAL aLocals[4], GetList := {}, GetOptions

 USE COLLECT NEW EXCLUSIVE

 LoadFields( aLocals )

 @ 5,10 DCSAY 'Description' GET cDesc ;
   GETID 'GET_DESC'

 @ 6,10 DCSAY '       Type' GET cType ;
   GETID 'GET_TYPE'

 @ 7,10 DCSAY '   Sub-Type' GET cSubType ;
   GETID 'GET_SUBTYPE'

 DCTOOLBAR oToolBar

 DCADDBUTTON CAPTION "Next" PARENT oToolBar ;
   SIZE 9 ;
   ACTION {||TestUpdated(GetList,aLocals),;
             dbSkip(1), ;
             LoadFields(aLocals), ;
             DC_GetRefresh(GetList),;
             DC_GetOrigSet(GetList) }

 DCADDBUTTON CAPTION "Prev" PARENT oToolBar ;
   SIZE 9 ;
   ACTION {||TestUpdated(GetList,aLocals),;
             dbSkip(-1), ;
             LoadFields(aLocals), ;
             DC_GetRefresh(GetList),;
             DC_GetOrigSet(GetList) }

 DCADDBUTTON CAPTION 'Desc' PARENT oToolBar ;
  SIZE 9 ;
  ACTION {||SetAppFocus(DC_GETOBJECT(GetList,'GET_DESC'))}

 DCADDBUTTON CAPTION 'Type' PARENT oToolBar ;
  SIZE 9 ;
  ACTION {||SetAppFocus(DC_GETOBJECT(GetList,'GET_TYPE'))}

 DCADDBUTTON CAPTION 'SubType' PARENT oToolBar ;
  SIZE 9 ;
  ACTION {||SetAppFocus(DC_GETOBJECT(GetList,'GET_SUBTYPE'))}

 DCREAD GUI ;
   FIT ;
   ADDBUTTONS

 RETURN

 /* ------------- */

 STATIC function LoadFields( aLocals )

 cDesc    := COLLECT->descrip
 cType    := COLLECT->type
 cSubType := COLLECT->sub_type

 RETURN nil

 /* ------------- */

 STATIC FUNCTION SaveFields( aLocals )

 REPLACE COLLECT->descrip  WITH cDesc
 REPLACE COLLECT->type     WITH cType
 REPLACE COLLECT->sub_type WITH cSubType

 RETURN nil

 /* ------------- */

 STATIC FUNCTION TestUpdated ( GetList, aLocals )

 IF DC_GETORIGUPDATED( GetList )
   IF DC_MsgBox(,,{'Data has been modified. Save Changes?'},,,,.t.)
     SaveFields( aLocals )
   ENDIF
 ENDIF
 RETURN nil

Files:

_DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readgui()
   dc_getobjectid()


dc_getobjectid()

Return a the ID of an object

DC_GETOBJECTID() is used to return a the ID of an object.<br><br> An ID is assigned via the ID <id> clause for each GetList command. <br><br>

Syntax:

DC_GetObject ( <oXbp>, ;
               <aGetList> ) -> cID

Returns:

 A character string.

Arguments:

<oXbp> is any object that was created using DC* commands.

<aGetList> is an array containing a list of Get objects.

Examples:

 -- Example 1 --

 #include 'dcdialog.ch'

 PROCEDURE XTest()

 @ 1,1 dcpushbutton caption "Test" id 'TEST' size 12,1 action ;
  {|a,b,o|DC_DebugQout(DC_GetObjectID(o,GetList))}

 DCREAD GUI FIT

 RETURN

Files:

_DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readgui()
   dc_getobject()


dc_getoptdefault()

Set the Default options for the GUI Reader

DC_GetOptDefault() is used to set the default options for the GUI reader. An array of information is passed to the function with the default values.<br><br>

Syntax:

 DC_GetOptDefault( [<aGetOptions>] ) -> aDefaultOptions

Returns:

 An array.

Arguments:

<aGetOptions> is an optional array of options default options
to set for the GUI reader.

Element   Type  Default   Description
-------   ----  --------  ------------------------------------
   1       C     nil      Window Name
   2       C     nil      Window Title
   3       N     24*20    Window Height (pixels)
   4       N     80*7     Window Width (pixels)
   5       N     20       Row Spaces (pixels)
   6       N     nil      Say Width (pixels)
   7       C     nil      Say Font
   8       C     nil      Get Font
   9       N     nil      Get Height (pixels)
  10       A     nil      Added buttons
  11       N     nil      Window Start Row (pixels)
  12       N     nil      Window Start Column (pixels)
  13       N     0        Window Row Offset (pixels)
  14       N     0        Window Column Offset (pixels)                                    /* nGETOPT_COLOFFSET */   ;
  15       L     .f.      Design Mode
  16       C     nil      Menu Name
  17       L     .f.      Pixel Mode
  18       X     nil      Spare
  19       N     1        Window Icon (resource number)
  20       L     .f.      Logical Gets are Checkboxes
  21       C     ''       Help File Name
  22       L     .f.      Objects are visible
  23       L     .t.      Translate text coordinates
  24       L     .t.      Says are Right Justified
  25       N     nil      Window BitMap (resource number)
  26       A     nil      Presentation Parameters
  27       N     nil      Background color of Window
  28       N     nil      Say Option (text justification)
  29       B     nil      Evaluation Code Block
  30       N     nil      Modal State
  31       N     nil      Says Height (pixels)
  32       L     nil      Minimize Button
  33       L     nil      Maximize Button
  34       L     .f.      Tab Stops
  35       A   {.f.,nil}  Abort Query Option
  36       N     20       Row Pixels
  37       N     7.0      Column Pixels
  38       L     .t.      Enable Escape Key
  39       C     ''       Source Code File
  40       A   { 1,0 }    ToolTip Color, ForeGround/BackGround
  41       N     nil      Border
  42       L     .f.      Validate on Exit
  43       A   {.f.,nil}  Close Query Option
  44       L    .f.       No Task List
  45       N     nil      Window Minimum Size
  46       N     nil      Window Maximum Size
  47       L     .f.      No Window Resize
  48       L     .f.      No Window Title bar
  49       L     .f.      No Window Move with owner
  50       N     0        Window Origin
  51       N     0        Hilite Gets Color
  52       L    .t.       Supervise Gets
  53       L    .f.       Hide Window
  54       L    .f.       No Busy Pointer
  55       C    ''        Busy Message
  56       N    327748    Dot Prompt Hot Key
  57       L    .f.       Cascade Windows
  58       L    .f.       AutoResize
  59       A    nil       Color Gets, ForeGround/BackGround
  60       L    .t.       Confirm
  61       N    10        Fitpad (pixels)
  62       N     0        Button Alignment
  63       A   {.f.,nil}  Exit Query
  64       N    nil       Disable Color (BackGround)

Notes:

See DCGETOPTIONS for a description of each option.

Examples:

FUNCTION X_test()

LOCAL GetOptions

DCGETOPTIONS ;
  ROWSPACE 15 ;
  ROWPIXELS 15 ;
  COLPIXELS 6.5 ;
  NOESCAPEKEY ;
  HILITEGETS GRA_CLR_RED ;
  TABSTOP

DC_GetOptDefault( GetOptions )

RETURN nil

Files:

_DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readgui()
   DCGETOPTIONS


dc_getorigset()

Set the original values of the Dialog items in the Getlist

DC_GETORIGSET() is used to store the current value of all the GETS in the GUI Getlist to the ORIGINAL value element of each Getlist array object. The original value is then tested against the current value with DC_GETORIGUPDATED() to test whether or not any values referenced in the Getlist have changed or been updated.<br><br>

Syntax:

DC_GetOrigSet ( <aGetList>, ;
                [<ancGroup>] ) -> nil

Returns:

 A logical value.

Arguments:

<aGetList> is an array containing a list of Get objects to
refresh.  The GetList must a Gui-based Get List compatible
with DC_ReadGets() or DC_ReadGui().

<ancGroup> is the GetList group to set.  Each item in the
GetList may be assigned a group name or number via the
GROUP <ancGroup> clause.  If a numeric or character value is
passed, then only the items in the GetList which match <ancGroup>
will be set.  <ancGroup> may consist of an array of numeric values
or character values so that more than one group may be set.
If <ancGroup> is a nil then all items in the GetList will be
set.

Examples:

 #define cPlayer    aLocals[1]
 #define cTeam      aLocals[2]
 #define cLeague    aLocals[3]
 #define oToolBar   aLocals[4]

 LOCAL aLocals[4], GetList := {}

 USE BASEBALL

 LoadFields( aLocals )

 @ 10,10 SAY 'Player Name' GET cPlayer
 @ 12,10 SAY '  Team Name' GET cTeam
 @ 14,10 SAY 'League Name' GET cLeague

 DCTOOLBAR oToolBar

 DCADDBUTTON "Next" PARENT oToolBar ;
    ACTION {||TestUpdated(GetList,aLocals),;
              dbSkip(1),
              LoadFields(aLocals),
              DC_GetRefresh(GetList),;
              DC_GETORIGSET(GetList) }

 DCADDBUTTON "Prev" PARENT oToolBar ;
    ACTION {||TestUpdated(GetList,aLocals),;
              dbSkip(-1),
              LoadFields(aLocals),
              DC_GetRefresh(GetList),;
              DC_GETORIGSET(GetList) }

 DC_ReadGets(Getlist)

 /* ------------- */

 STATIC function LoadFields( aLocals )

 cPlayer := BASEBALL->player
 cTeam   := BASEBALL->team
 cLeague := BASEBALL->league

 RETURN nil

 /* ------------- */

 STATIC FUNCTION SaveFields( aLocals )

 REPLACE BASEBALL->player WITH cPlayer
 REPLACE BASEBALL->team   WITH cTeam
 REPLACE BASEBALL->league WITH cLeague

 RETURN nil

 /* ------------- */

 STATIC FUNCTION TestUpdated ( GetList, aLocals )

 IF DC_GetOrigUpdated( GetList )
   IF DC_MsgBox(,,{"Data has been modified. Save Changes?'},,,,.t.)
     SaveFields( aLocals )
   ENDIF
 ENDIF
 RETURN nil

Files:

_DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readgui()
   dc_getorigset()
   dc_getrefresh()


dc_getorigupdated()

Test the original values of the Dialog items in the Getlist

DC_GETORIGUPDATED() is used to test the current value of all the GETS or a specified GET in the GUI Getlist to the ORIGINAL value element of the Getlist array object. If the current value of the GET is not equal to the original value, the function returns a .TRUE. If the current value of the GET equals the original value, the function returns a .FALSE.<br><br><br><br>

Syntax:

DC_GetOrigUpdated ( <aGetList>,  ;
                    [<cID> | <nItem>], ;
                    [<ancGroup>], ;
                    [<lVerbose>] ) -> lStatus

Returns:

 A logical value.

Arguments:

<aGetList> is an array containing a list of Get objects to
refresh.  The GetList must a Gui-based Get List compatible
with DC_ReadGets() or DC_ReadGui().

<cID> is the ID of the GET object.  This is the ID that was
assigned with the ID <cId> argument of the command that added
the object to the GetList.

<nItem> is the item number in the GetList.  If no <cId> or
<nItem> argument is passed, then the entire GetList will be
tested, otherwise only the specified ID or ITEM will be
tested.

<ancGroup> is the GetList group to test.  Each item in the
GetList may be assigned a group name or number via the
GROUP <ancGroup> clause.  If a numeric or character value is
passed, then only the items in the GetList which match <ancGroup>
will be tested.  <ancGroup> may consist of an array of numeric
values or character values so that more than one group may be
tested. If <ancGroup> is a nil then all items in the GetList will
be tested.

<lVerbose> if .TRUE. will display a message window about which
item of the GetList has been updated.  This helps in debugging.
The default is .FALSE.

Examples:

 #include 'dcdialog.ch'

 PROCEDURE XTest()

 #define cDesc      aLocals[1]
 #define cType      aLocals[2]
 #define cSubType   aLocals[3]
 #define oToolBar   aLocals[4]

 LOCAL aLocals[4], GetList := {}, GetOptions

 USE COLLECT NEW EXCLUSIVE

 LoadFields( aLocals )

 @ 5,10 DCSAY 'Description' GET cDesc
 @ 6,10 DCSAY '       Type' GET cType
 @ 7,10 DCSAY '   Sub-Type' GET cSubType

 DCTOOLBAR oToolBar

 DCADDBUTTON CAPTION "Next" PARENT oToolBar ;
   SIZE 9 ;
   ACTION {||TestUpdated(GetList,aLocals),;
             dbSkip(1), ;
             LoadFields(aLocals), ;
             DC_GetRefresh(GetList),;
             DC_GetOrigSet(GetList) }

 DCADDBUTTON CAPTION "Prev" PARENT oToolBar ;
   SIZE 9 ;
   ACTION {||TestUpdated(GetList,aLocals),;
             dbSkip(-1), ;
             LoadFields(aLocals), ;
             DC_GetRefresh(GetList),;
             DC_GetOrigSet(GetList) }

 DCGETOPTIONS ;
   WINDOW WIDTH 300 ;
   WINDOW HEIGHT 300

 DCREAD GUI ;
   FIT ;
   OPTIONS GetOptions ;
   ADDBUTTONS

 RETURN

 /* ------------- */

 STATIC function LoadFields( aLocals )

 cDesc    := COLLECT->descrip
 cType    := COLLECT->type
 cSubType := COLLECT->sub_type

 RETURN nil

 /* ------------- */

 STATIC FUNCTION SaveFields( aLocals )

 REPLACE COLLECT->descrip  WITH cDesc
 REPLACE COLLECT->type     WITH cType
 REPLACE COLLECT->sub_type WITH cSubType

 RETURN nil

 /* ------------- */

 STATIC FUNCTION TestUpdated ( GetList, aLocals )

 IF DC_GETORIGUPDATED( GetList )
   IF DC_MsgBox(,,{'Data has been modified. Save Changes?'},,,,.t.)
     SaveFields( aLocals )
   ENDIF
 ENDIF
 RETURN nil

Files:

_DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readgui()
   dc_getorigset()
   dc_getrefresh()


dc_getpopupautohide()

A Get-Set function for hiding un-focused POPUP buttons

DC_GetPopupAutoHide() is a Get-Set function used to hide @..DCSAY..GET..POPUP buttons until the associated GET receives focus.<br><br>

Syntax:

DC_GetPopupAutoHide( [<lSetting>] ) -> lOldSetting

Returns:

 The previous setting.

Arguments:

<lSetting> if .TRUE. will cause POPUP buttons that are attached
to @..DCSAY..GET objects via the POPUP clause, to be hidden
whenever any associated EDITPROTECT codeblock evaluates .TRUE.
The default is .FALSE.  The default behavior is to disable the
button from activation.

Examples:

For a functionality equivalent to Microsoft's Outlook Contact
Manager, include the following at the start of your application:

DC_GetPopupCaption({ '', BITMAP_PENCIL_S, 0 })
DC_GetPopupAutoHide(.t.)

Files:

_DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   @ DCSAY GET


dc_getpopupcaption()

Set the default caption for the POPUP pushbutton

DC_GETPOPUPCAPTION() is used to change the default caption for the POPUP pushbutton which is used with the POPUP clause of the @ DCSAY..GET and @ DCGET commands. The caption defaults to three dots.

Syntax:

DC_GetPopupCaption( [<aCaption>] ) -> aOldCaption

Returns:

 The previous setting of the font and caption.

Arguments:

<aCaption> is an array of six elements:

1. The font of the caption.  This must be a standard compound
   font name.

2. A character string or Bitmap resource for the caption.  If
   it is a numeric value, the resource must be linked into the
   .EXE.

3. A numeric value defining the style of popup button.

   0 - Create the button on the same parent as the GET.  The
       height and width is the same as the height of the GET.
       The button is placed behind the GET. (DEFAULT).

   1 - Create the button within the GET object at the end of
       the GET.  This is visually identical to a button in
       a combobox.

4. A numeric value (in pixels) equivalent to the default width
   of the button

5. A numeric value (in pixels) equivalent to the default height
   of the button

6. A numeric value for the Hot-Key to use to invoke the button
   when the associated GET has focus.  Keys are defined in
   APPEVENT.CH are are prefixed with xbeK_.

Notes:

Examples:

#include "DCBITMAP.CH"

FUNCTION XTest()

LOCAL GetList := {}, dDate := Date(), xCaption

DC_GETPOPUPCAPTION( { '10.Marlett', 'u' } ) // down arrow

@ 1,1 DCSAY 'Enter Date ' GET dDate POPUP {|d|DC_PopDate(d)}

DCREAD GUI FIT ADDBUTTONS

RETURN dDate

Files:

_DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   @ DCSAY GET


dc_getpopupprotecthide()

A Get-Set function for hiding protected POPUP buttons

DC_GetPopupProtectHide() is a Get-Set function used to hide @..DCSAY..GET..POPUP buttons when the EDITPROTECT codeblock evaluates .TRUE.<br><br>

Syntax:

DC_GetPopupProtectHide( [<lSetting>] ) -> lOldSetting

Returns:

 The previous setting.

Arguments:

<lSetting> if .TRUE. will cause POPUP buttons that are attached
to @..DCSAY..GET objects via the POPUP clause, to be hidden
whenever any associated EDITPROTECT codeblock evaluates .TRUE.
The default is .FALSE.  The default behavior is to disable the
button from activation.

Examples:

FUNCTION XTest()

LOCAL GetList := {}, dDate := Date(), lEditMode := .f.

DC_GETPOPUPPROTECTHIDE( .t. )

@ 1,1 DCSAY 'Enter Date ' GET dDate POPUP {|d|DC_PopDate(d)} ;
  EDITPROTECT {||!lEditMode}

DCREAD GUI FIT ADDBUTTONS

RETURN dDate

Files:

_DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   @ DCSAY GET


dc_getprogress()

Update a Progress bar object

DC_GETPROGRESS() is used in conjunction with @..DCPROGRESS to display a progress bar any type of operation. The progress bar will fill in the specified area with a graphic progress bar.

Syntax:

DC_GetProgress ( <oProgress>, ;
                 <nCurrCount>, ;
                 <nMaxCount>, ;
                 <nEvery> ) -> .T.

Returns:

 A logical .TRUE.

Arguments:

<oProgress> is the Progress bar object created by the
@..DCPROGRESS command.

<nCurrCount> is the current count.  For example, when updating
a progress bar while copying records, this would be RecNo().

<nMaxCount> is the maximum count.  For example, when updating a
progress bar while copying records, this would be RecCount().

<nEvery> is the number of records that are traversed before the
progress bar is updated.

Examples:

 #include 'dcdialog.ch'
 #include 'gra.ch'

 PROCEDURE XTest()

 LOCAL Getlist := {}, oProgress, oDialog

 USE customer

 DC_Gui(.t.)

 @ 2,5 DCSAY 'Exporting Data to JUNK.DBF'

 @ 4,5 DCPROGRESS oProgress ;
       SIZE 60,1.5 ;
       MAXCOUNT RecCount() COLOR GRA_CLR_BLUE

 DCREAD GUI TITLE 'My Test Dialog' ;
   PARENT @oDialog ;
   FIT ;
   EXIT

 oDialog:show()

 COPY TO junk WHILE DC_GetProgress( oProgress, RecNo() )

 DC_MsgBox('Done')

 oDialog:Destroy()

 RETURN

Files:

_DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   @ DCPROGRESS
   dc_progress
   dc_working


dc_getproperty()

Return the value of a Getlist property from an object

DC_GETPROPERTY() is used to return a specified property from the GetList that is associated with a specified object.<br><br> <br><br>

Syntax:

DC_GetProperty ( <oXbp>, ;
                 <nProperty>, ;
                 [@<aGetList>], ;
                 [@<aGetListItem>], ;
                 [@<nPointer>] ) -> xValue

Returns:

A value from the Getlist associated with the object and property
index.

Arguments:

<oXbp> is a pointer to any object that was created by DC_ReadGui().

<nProperty> is a numeric value defined in DCDIALOG.CH.  See
DIALOG GETLIST for a definition of these manifest constants.

@<aGetList> is a variable, passed by reference, to store a pointer
to the GetList that is associated with the object.

@<aGetListItem> is a variable, passed by reference, to store a
pointer to the GetList Item that is associated with the object.

@<nPointer> is a variable, passed by reference, to store the
numeric position (array element #) of this item in the GetList.

Notes:

Examples:

 -- Example 1 --

 #include 'dcdialog.ch'

 PROCEDURE XTest()

 @ 1,1 DCPUSHBUTTON CAPTION 'Testing' SIZE 10,1 ;
       ACTION {|o|GetCaption(o)}

 DCREAD GUI FIT ADDBUTTONS

 RETURN nil

 * -------------

 STATIC FUNCTION GetCaption( oXbp )

 ? DC_GetProperty( oXbp, cGETLIST_CAPTION )

 RETURN nil

Files:

_DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_setproperty()
   dc_getobject()
   DIALOG GETLIST


dc_getreadinsert()

a Get-Set function for establishing default Insert mode

DC_GetReadInsert() is a Get/Set function used to set the default Insert mode when entering a new dialog.

Syntax:

DC_GetReadInsert( [<nInsertMode>] ) -> <nOldInsertMode>

Returns:

A logical value.

Arguments:

<nInsertMode> will set the insert mode based on the following table:

nMode   Description
-----   -------------------------------------------
  2     Set Insert Mode ON
  1     Set Insert Mode OFF (Overstrike ON)
  0     Do not change Insert/Overstrike mode
  .T.   Set Insert Mode ON (compatability with build 232)
  .F.   Set Insert Mode OFF (compatability with build 232)

Examples:

@ 1,1 DCGET dDate
DC_GetReadInsertMode(.f.) // set overstrike mode
DCREAD GUI FIT

Files:

_DCXBPGT.PRG


dc_getrefresh()

Refresh the display of all objects in the Get List

DC_GETREFRESH() is used to refresh all the objects in the GetList array that have a datalink via a codeblock. Use this function to update the dialogue screen after changing the value of one of the variables via a button action or in your custom event handler.<br><br> DC_GetRefreshBlock() is a Get-Set function that is used to post a code block to call every time DC_GetRefresh() is called. This may be used to help debug problems with refreshing.

Syntax:

DC_GetRefresh ( <aGetList|oXbp>, ;
                [<nElement> | <cID> ], ;
                [<nRefreshMode>], ;
                [<aRefreshList>], ;
                [<ancGroup>], ;
                [<lDataLink>], ;
                [<lInvisible>] ) -> nil

Returns:

 .TRUE. if any gets were updated, .FALSE. otherwise.

Arguments:

<aGetList|oXbp> is an array containing a list of Get objects to
refresh.  The GetList may be Dual-Mode Getlist compatible
with DC_ReadGets() or DC_ReadGui() or a text-based GetList
compatible with DC_ReadModal().  Alternatively, it may be a pointer
to an Xbase++ object.  If it is an object, then the remaining
parameters are ignored.  If it is an object, then all objects
that are also descendents of <oXbp> will also be refreshed.

The second parameter may be a numeric value, a character string,
or a NIL.  If it is a numeric value, then <nElement> is a
specific GetList element to refresh.  This must be a number from
1 to the Length of <aGetList>. If it is a character string, then
<cID> is a character string equal to the ID of the GetList element
to refresh. If no parameter is passed then the entire Getlist will
be refreshed.

<nRefreshMode> and <aRefreshList> are used together to refresh
the Getlist based on the Refresh Mode <nRefreshMode> and the
contents of <aRefreshList>.  These parameters can be used to
refresh all items in the Getlist "except" a specified list
or only those in a specified list.  <aRefreshList> is an array
of Character strings matching the cGETLIST_ID element of the
GetList if <nRefreshMode> is DCGETREFRESH_ID_* -or- <aRefreshList>
is an array of Numeric values matching the nGETLIST_TYPE of the
GetList if <nRefreshMode> is DCGETREFRESH_TYPE_*.

<nRefreshMode>               Description
---------------              ---------------------------------------
DCGETREFRESH_ID_INCLUDE      Refresh only the items with IDs that
                             are included in <aRefreshList>.

DCGETREFRESH_ID_EXCLUDE      Refresh all items with IDs that are
                             NOT included in <aRefreshList>.

DCGETREFRESH_TYPE_INCLUDE    Refresh only the items with TYPEs that
                             are included in <aRefreshList>.

DCGETREFRESH_TYPE_EXCLUDE    Refresh all items with TYPEs that are
                             NOT included in <aRefreshList>.

<ancGroup> is the GetList group to refresh.  Each item in the
GetList may be assigned a group name or number via the
GROUP <ancGroup> clause.  If a numeric or character value is passed
then only the items in the GetList which match <ancGroup> will be
refreshed.  <ancGroup> may consist of an array of numeric values
or character values so that more than one group may be refreshed.
If <ancGroup> is a nil then all items in the GetList will be
refreshed.

If <lDataLink> is .TRUE. (default) any code blocks associated
with the DATALINK clause of DC* commands will also be evaluated
when the associated object is refreshed.  If <lDataLink> is
.FALSE. then the DATALINK code block is ignored during refresh.

If <lInvisible> is .TRUE. (default) any object that is not
visible, ie, oXbp:isVisible() returns a false, will be refreshed.
If <lInvisible> is .FALSE. invisible objects will not be refreshed.
NOTE: Objects are considered invisible if they are hidden or if
they are on tabpages that are minimimized.  Setting <lInvisible>
to .FALSE. can improved performance on applications with many
objects and many tabpages.

Notes:

DC_GetRefresh() will not refresh DCGRA* items, such as @ DCGRABOX,@ DCGRASTRING or @ DCSAY..GRASTRING. Use the functionDC_PaintGraControls().

Examples:

 -- Example 1 --

 #include 'dcdialog.ch'

 PROCEDURE XTest()

 #define cDesc      aLocals[1]
 #define cType      aLocals[2]
 #define cSubType   aLocals[3]
 #define oToolBar   aLocals[4]

 LOCAL aLocals[4], GetList := {}, GetOptions

 USE COLLECT NEW EXCLUSIVE

 LoadFields( aLocals )

 @ 5,10 DCSAY 'Description' GET cDesc
 @ 6,10 DCSAY '       Type' GET cType
 @ 7,10 DCSAY '   Sub-Type' GET cSubType

 DCTOOLBAR oToolBar

 DCADDBUTTON CAPTION "Next" PARENT oToolBar ;
   SIZE 9 ;
   ACTION {||TestUpdated(GetList,aLocals),;
             dbSkip(1), ;
             LoadFields(aLocals), ;
             DC_GetRefresh(GetList),;
             DC_GetOrigSet(GetList) }

 DCADDBUTTON CAPTION "Prev" PARENT oToolBar ;
   SIZE 9 ;
   ACTION {||TestUpdated(GetList,aLocals),;
             dbSkip(-1), ;
             LoadFields(aLocals), ;
             DC_GetRefresh(GetList),;
             DC_GetOrigSet(GetList) }

 DCGETOPTIONS ;
   WINDOW WIDTH 300 ;
   WINDOW HEIGHT 300

 DCREAD GUI ;
   FIT ;
   OPTIONS GetOptions ;
   ADDBUTTONS

 RETURN

 /* ------------- */

 STATIC function LoadFields( aLocals )

 cDesc    := COLLECT->descrip
 cType    := COLLECT->type
 cSubType := COLLECT->sub_type

 RETURN nil

 /* ------------- */

 STATIC FUNCTION SaveFields( aLocals )

 REPLACE COLLECT->descrip  WITH cDesc
 REPLACE COLLECT->type     WITH cType
 REPLACE COLLECT->sub_type WITH cSubType

 RETURN nil

 /* ------------- */

 STATIC FUNCTION TestUpdated ( GetList, aLocals )

 IF DC_GETORIGUPDATED( GetList )
   IF DC_MsgBox(,,{'Data has been modified. Save Changes?'},,,,.t.)
     SaveFields( aLocals )
   ENDIF
 ENDIF
 RETURN nil

 -- Example 2 ---

 /* This example refreshes all items in the Getlist except
    GETLIST_BROWSE type objects.  It is not always necessary to
    refresh BROWSE objects and it can slow the system when
    refreshing Browses often. */

 #include 'dcdialog.ch'

 DC_GETREFRESH( aGetList, nil, ;
                DCGETREFRESH_TYPE_EXCLUDE, ;
                {GETLIST_BROWSE} )

Files:

_DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_getrefreshblock()
   dc_readgui()
   dc_getwhen()


dc_getrefreshblock()

Post a code block for debugging DC_GetRefresh() problems

DC_GetRefreshBlock() is used to help in debugging DC_GetRefresh() calls.<br><br>This is a handy function to determine where in the application code, DC_GetRefresh() is being called. Often times, it is called more often than needed, thereby causing unneedy screen flickering and/or slowness.<br><br>

Syntax:

DC_GetRefreshBlock( <bBlock> ) -> bOldBlock

Arguments:

<bBlock> is a code block to evaluate inside the DC_GetRefresh()
function.

The first 5 parameters that are passed to DC_GetRefresh() are
also passed to the code block:

<aGetList>, <nElement>, <nRefreshMode>, <aRefreshList>, <acGroup>

Examples:

DC_GetRefreshBlock( {|a,b,c,d,e|(dcbdebug a,b,c,d,e)}

Files:

_DCGETBX.PRG

See Also:

   dc_getrefresh()


dc_gettitlebarheight()

Get the height of Dialog Title Bars

DC_GetTitleBarHeight() returns the height (in pixels) of the Dialog window title bar. This height is normally set by the user after clicking on "Desktop Properties".

Syntax:

DC_GetTitleBarHeight() -> nHeight

Returns:

A numeric value.

Arguments:

None.

Examples:

? DC_GetTitleBarHeight()
21

Files:

_DCFUNCT.PRG, DCLIPX.DLL


dc_getvalidate()

Run validation logic in the GetList

DC_GetValidate() is used to test or run the validation code block associated with a specifed GET.<br><br> DC_GetValidate() is called automatically in DC_ReadGuiEventLoop() after events that may change values referenced in a GET.<br><br><br><br>

Syntax:

 DC_GetValidate( oXbp, ;
                [<lPassBuffer>], ;
                [<lTestForBlock>] ) -> lStatus

Returns:

 The logical value returned by the VALID code block associated
 with the Xbase Parts object.

Arguments:

<oXbp> is the Xbase Parts object to validate.  This is any
object created by a DC* command in the GetList that also has
an associated VALID clause.

<lPassBuffer> if .TRUE. will pass the contents of the display
buffer to the validation code block, otherwise if .FALSE.
(default), a pointer to the object will be passed to the
validation code block.

<lTestForBlock> if .TRUE. will only test for the existence of a
validation code block associated with an object but will not
evaluate the code block.  If a code block exists, then the
function will return .TRUE. otherwise it will return .FALSE.

Examples:

oXbp := SetAppFocus()
? DC_GetValidate( oXbp )

Files:

_DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readgui()
   dc_getrefresh()
   dc_getvalidblock()
   dc_getvalidateonchange()


dc_getvalidateonchange()

A Get-Set function to determine Validation rule

DC_GetValidateOnChange() is a get-set function that is used to modify the behavior of GET validations.<br><br><br><br> <br><br>

Syntax:

DC_GetValidateOnChange( [<lSetting>] ) -> lOldSetting

Arguments:

<lSetting> if .TRUE. will cause the validation code block
only to be evaluated if the value of the Get has changed.  The
default is .FALSE.

Files:

_DCGETBX.PRG, DCLIPX.DLL

See Also:

   dc_getvalidate()


dc_getvalidblock()

A Get-Set function for posting a default validation block

DC_GetValidBlock() is a Get-Set function that is used to post a "default" validation code block for @..DCSAY..GET and @..DCGET objects. The default code block will be evaluated first before evaluating any code block posted with the VALID clause. This is handy for special date validations.

Syntax:

DC_GetValidBlock( [<bValidate>] ) -> bOldValidate

Returns:

The previously posted code block.

Arguments:

<bValidate> is a code block that will be evaluated when
any DC_XbpGet() object loses focus.  The object will be
passed to the code block.  The code block must return a
logical value.  If it returns a .TRUE., then control will
be passed to the validation routine that evaluates the
specific validation block for the object.  If it returns
a .FALSE., then the object cannot lose focus.

Examples:

FUNCTION XTest()

LOCAL GetList[0], cTime := '  :  :  '

DC_GetValidBlock({|o|MySpecialValidator(o)})

@ 1,1 DCSAY 'Enter Time' GET cTime PICT '99:99:99'

DCREAD GUI FIT ADDBUTTONS ENTEREXIT

RETURN nil

* -----------

FUNCTION MySpecialValidator( oGet )

LOCAL xValue := oGet:get:varget()

IF Valtype(xValue) == 'C' .AND. Len(xValue) = 8 .AND. ;
   xValue[3] == ':' .AND. xValue[6] == ':'
  // this is a "Time" Get
  nHours := Min(Val(Substr(xValue,1,2)),23)
  nMinutes := Min(Val(Substr(xValue,4,2)),59)
  nSeconds := Min(Val(Substr(xValue,7,2)),59)
  xValue := DC_PadZero(Str(nHours,2)) + ':' + ;
            DC_PadZero(Str(nMinutes,2)) + ':' + ;
            DC_PadZero(Str(nSeconds))
  oGet:_assign(xValue)
ENDIF

RETURN .t.

Files:

_DCGETBX.PRG, DCLIPX.DLL

See Also:

   @ DCSAY
   dc_getvalidate()
   dc_getvalidateonchange()


dc_getwhen()

Refresh the WHEN/HIDE status of object(s) in the GetList

DC_GetWhen() is used to refresh the WHEN/HIDE status of objects in the GetList. If the WHEN clause or HIDE clause is used with a DC* command, it is the function DC_GetWhen() that evaluates the code block associated with the WHEN or HIDE clauses and uses the :disable()/:enable and/or :hide()/:show() method of the Xbase Parts class dependent on the value returned by the associated code block.<br><br> DC_GetWhen() is called automatically in DC_ReadGuiEventLoop() after events that may change values referenced in WHEN/HIDE code blocks. DC_GetWhen() is also called from DC_GetRefresh().<br><br><br><br>

Syntax:

DC_GetWhen ( <aGetList | oXbp>, ;
             [<nElement>], ;
             [<lTestProtect>], ;
             [<acID>], ;
             [<acGroup> ) -> nil

Returns:

 Nil.

Arguments:

<aGetList> is an array containing a list of Get objects to
refresh.  Alternatively, the first parameter may be an object
of the DC_Xbp*() class.  If this paramter is an object, then
the remaining parameters are not used.

<nElement> is the element number of the GetList to test.  If
this parameter is not passed, then all items in the GetList will
be tested.

<lTestProtect> is reserved for internal use.

<acID> is an Object ID or array of ID's to evaluate. When this
parameter is used, only this ID or list of ID's will be refreshed.

<acGroup> is a Group ID or array of Group ID's to evaluate.  When
this parameter is used, only this Group or list of Groups will
be refreshed.

Examples:

-- Example 1 --

oXbp := SetAppFocus()
aGetList := oXbp:cargo[2]
nElement := oXbp:cargo[1]
DC_GetWhen( aGetList, nElement )

-- Example 2 --

DC_GetWhen( GetList,,,{'BUTTON1','BUTTON2'} )

-- Example 3 --

DC_GetWhen( GetList,,,,'GROUP1' )

Files:

_DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readgui()
   dc_getrefresh()
   dc_readguieventloop()


dc_getwhenonbrowseitemmarked()

Get-set function that enable DC_GetWhen() on item marked event

DC_GetWhenOnBrowseItemMarked() is a Get-Set function that enables DC_GetWhen() calls when an xbeBRW_ItemMarked event occurs.<br><br>This would be used in case it is needed to insure that all WHEN and HIDE clauses in a dialog are evaluated any time the row pointer is moved in the browse. The default is .FALSE. for performance reasons.<br><br>

Syntax:

DC_GetWhenOnBrowseItemMarked( [<lEnable> ] ) -> lOldEnable

Arguments:

<lEnable> if .TRUE. will enable evaluation of HIDE and WHEN clauses.
The default is .FALSE.

Files:

_dcxbrow.prg, dclipx.dll

See Also:

   @ DCBROWSE


dc_getworkarea()

Get the actual working area of the Desktop

DC_GetWorkArea() returns an array of 4 elements containing the usable work area of the AppDesktop(). AppDeskTop():currentSize() will return the full size of the desktop, however, the user may have limited the useful area by setting toolbars on the desktop as "always on top". DC_GetWorkArea() is used to determine the useable area of the desktop.<br><br>Retrieves the size of the work area on the primary display monitor. The work area is the portion of the screen not obscured by the system taskbar or by application desktop toolbars.

Syntax:

DC_GetWorkArea() -> aCoords

Returns:

An array of 4 elements:
{ left, top, right, bottom }

left
Specifies the x-coordinate of the upper-left corner of the
rectangle.

top
Specifies the y-coordinate of the upper-left corner of the
rectangle.

right
Specifies the x-coordinate of the lower-right corner of the
rectangle.

bottom
Specifies the y-coordinate of the lower-right corner of the
rectangle.

Arguments:

None.

Examples:

// This example will create a dialog window that is sized and
positioned to fill the useable workarea of the desktop.

aWorkArea := DC_GetWorkArea()

nHeight := aWorkArea[4] - aWorkArea[2]
nWidth  := aWorkArea[3] - aWorkArea[1]

oDlg := XbpDialog():new( AppDeskTop(), , ;
      {aWorkArea[1],AppDeskTop():currentSize()[2]-aWorkArea[4]}, ;
      {nWidth,nHeight}, , .F.)

Files:

_DCFUNCT.PRG, DCLIPX.DLL


dc_gotoget()

Go directly to a desired GET

DC_GOTOGET() is handy if you have a large table of GETS on the screen and don't have a mouse, but want to give the operator an opportunity to go directly to a GET # by typing in the GET number.<br><br>

Syntax:

DC_GoToGet () -> nil

Returns:

 NIL

Arguments:

 none.

Notes:

This function only works with DC_ReadModal(), NOT ReadModal().

Examples:

 SetKey( -1, { || DC_GOTOGET() } )
 DC_ReadModal( GetList )

Files:

_DCGETSY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()


dc_gra2color()

Convert GUI compatible color to a color string

DC_GRA2COLOR() is used to convert an 2 element array containing a foreground and background color that are compatible with GUI objects to a color string that is compatible with text objects.

Syntax:

DC_Gra2Color( <aColor> ) -> cColorString

Returns:

 A character string.

Arguments:

<aColor> is an array of two numeric elements.  The first
element is the foreground color.  The second element is the
background color.

Examples:

 #include "gra.ch"

 PROCEDURE Xtest()

 LOCAL aColor := { GRA_CLR_RED, GRA_CLR_WHITE }

 DC_Gui(.t.)

 DC_MsgBox( DC_Gra2Color( aColor ) )

 RETURN

Files:

_DCCOLOR.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_color2gra()


dc_graquerytextbox()

Get the width and height of a text string based on a font

DC_GraQueryTextBox() is used to calculate the width and height, in pixels, of a text string based on a specified font. This is basically a wrapper function for the Xbase++ function GraQueryTextBox() which is simpler to use.<br><br>

Syntax:

DC_GraQueryTextBox( <cString>, ;
                    <cFont> ) -> aSize

Returns:

A two element array of numeric values.

[1] - Width
[2] - Height

Arguments:

<cString> is a text string.

<cFont> is a character string containing the name of the font
which conforms to a standard Xbase++ font definition, such as
'12.Arial Bold'.

Examples:

PROCEDURE XTest( )

LOCAL i, j, cFont, nRow, lOk, GetList := {}, nHeight

FOR i := 8 TO 22 STEP 2
  cFont := Alltrim(Str(i)) + '.Arial'
  nHeight := DC_GraQueryTextBox( 'Text', cFont )[2]
  nRow := 1
  FOR j := 1 TO 10
    @ nRow, 0 DCSAY 'This is line ' + Alltrim(Str(j)) ;
            FONT cFont SAYSIZE 0 PIXEL
    nRow += nHeight
  NEXT
  DCREAD GUI FIT ADDBUTTONS TO lOk
  IF !lOk
    EXIT
  ENDIF
NEXT

RETURN

Files:

_DCFUNCT.PRG, DCLIPX.DLL


dc_groupboxfix()

A Get-Set function used to fix group box problem on XP

DC_GroupBoxFix() is a Get-Set function that is used to set the method in which DCGROUP static boxes will be created due to an Xbase++ anomoly that displays XbpRadioButton() objects incorrectly when the parent is a XbpStatic() type XBPSTATIC_TYPE_GROUPBOX and the application is using a MANIFEST file.<br><br>Run the sample program in \exp18\samples\xp for more information about using manifest files to display XP style dialog objects.<br><br>When set to .T., every DCGROUP command will create two XbpStatic() objects instead of one. The parent of the groupbox will be a static of type text and will be the exact same size. This eliminates the display problem under XP.

Syntax:

DC_GroupBoxFix( [<lFix>] ) -> lOldFix

Arguments:

<lFix> if .TRUE. will create two XbpStatic objects, if .FALSE.
will function normally and create only one XbpStatic object.

Examples:

#INCLUDE "dcdialog.CH"

FUNCTION main

LOCAL GetList[0], GetOptions, d := Date(), nGroup := 3, i, oGroup, oStatic, ;
      lCheck := .F.

IF 'Windows XP' $ Os() .AND. File('TEST.EXE.MANIFEST')
  DC_GroupBoxFix(.t.)
ENDIF

FOR i := 1 TO 10
  @ i,0 DCSAY 'Date ' + Alltrim(Str(i)) GET d POPUP {|d|DC_PopDate(d,,,,,,2)}
NEXT

@ 1,27 DCGROUP oGroup CAPTION 'Group Test' SIZE 20,10 PARENT oStatic

FOR i := 1 TO 4
  @ i,1 DCRADIO nGroup VALUE i PROMPT 'Radio Button ' + Alltrim(Str(i)) PARENT oGroup
NEXT

FOR i := 1 TO 4
  @ i+4,1 DCCHECKBOX lCheck PROMPT 'Check Box ' + Alltrim(Str(i)) PARENT oGroup
NEXT

FOR i := 1 TO 10
  @ i,50 DCPUSHBUTTON CAPTION 'Button ' + Alltrim(Str(i)) ;
    SIZE 10,1 ACTION {||MsgBox('button test')}
NEXT

DCGETOPTIONS ;
   SAYWIDTH 50 ;
   SAYRIGHTBOTTOM ;
   HILITEGETS GRA_CLR_RED ;
   COLORGETS { {GRA_CLR_RED,GRA_CLR_YELLOW} } ;
   BUTTONALIGN DCGUI_BUTTONALIGN_CENTER

DCREAD GUI ;
   FIT ;
   MODAL ;
   SETAPPWINDOW ;
   ADDBUTTONS ;
   OPTIONS GetOptions ;
   TITLE 'XP Manifest Sample'

RETURN nil

* -----------

PROC appsys
RETURN

Files:

_DCCLASS.PRG, DCLIPX.DLL


dc_gui()

Set the Dialogue mode to GUI or TEXT

DC_Gui() is used to set Text or Gui mode for Dual-Mode Functions. The eXPress++ library contains a variety of functions which operate in "Dual-Mode". When GUI mode is ON, the function uses a GUI dialogue based on Xbase Parts. When the GUI mode is OFF the function works in standard text-mode.<br><br>

Syntax:

 DC_Gui( [<lMode>] ) -> lOldMode

Returns:

 Tha previous setting of GUI mode.

Arguments:

<lMode> if .TRUE. sets GUI mode ON, if .FALSE. sets GUI mode OFF.
If <lMode> is not passed, then the GUI mode is not changed.

Examples:

  /*
  In this example, DC_ReadBox() and DC_Impl() will only
  display and restore the window in Text-Mode.  They are
  ignored in GUI mode.
  */

  #include "dcdialog.ch"

  PROCEDURE Xtest( lGui )

  LOCAL GetList := {}, GetOptions, aReadArea, cLastName := Space(15), ;
        cFirstName := Space(15), cCompany := Space(25), ;
        cStreet := Space(25), cCity := Space(25), cState := Space(2), ;
        cCountry := Space(25), cPhone := Space(15), cScrn, lOk

  lGui := IIF( Valtype(lGui)='L',lGui,.t.)

  DC_Gui(lGui)   //  set GUI mode

  cScrn := DC_ReadBox(3,5,15,75,,@aReadArea)

  @ 5,10 DCSAY ' Last Name' GET cLastName
  @ 5,40 DCSAY 'First Name' GET cFirstName
  @ 7,10 DCSAY '   Company' GET cCompany
  @ 8,10 DCSAY '    Street' GET cStreet
  @ 9,10 DCSAY '      City' GET cCity
  @10,10 DCSAY '     State' GET cState
  @11,10 DCSAY '   Country' GET cCountry
  @13,10 DCSAY '     Phone' GET cPhone PICT '(999)-999-9999'

  DCGETOPTIONS SAYWIDTH 70 SAYRIGHTJUST

  lOk := DC_ReadGets( GetList,"Enter Data",aReadArea,;
                      GetOptions )
  DC_Impl(cScrn)

  RETURN

Files:

_DCGUI.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()
   dc_readgui()
   GUI


dc_guiabrowse()

Browse a multi-dimensional array using Tree-View

DC_GUIABROWSE() is an array-browser that provides a tree-view style browse of any multi-dimensional array.

Syntax:

DC_GuiAbrowse( <aArray>, ;
               [<aRef>], ;
               [<oParent>], ;
               [<aPos>], ;
               [<aSize>], ;
               [<cTitle>], ;
               [<lHasButtons>], ;
               [<lHasLines>] ) -> oArrayTree

Returns:

A pointer to the tree-view object.

Arguments:

<aArray> is the multi-dimensional array to browse.

<aRef> is an optional reference array that is used to format the
data in the browse.  If <aRef> is a NIL then the tree view will
display the exact contents of the array.  <aRef> is an array of
5-element sub-arrays, 1 for each level of the array being browsed.
The sub-arrays are defined as follows:

 Element Type Description
 ------- ---- ----------------------------------------------------

   [1]     B  Optional code block used to format the displayed
              data.  The array item and it's ordinal position
              within the array are passed as parameters.
              examples: {|a,n|a[1]}
                        {|a,n|filedata(a,n)}

   [2]     N  The resource ID of a bitmap or icon image to
              visualize the normal state of the array item
              (not marked and not expanded).

   [3]     N  The resource ID of a bitmap or icon image to
              visualize the marked state of the array item.

   [4]     N  The resource ID of a bitmap or icon image to
              visualize the expanded state of the array item.

   [5]     A  An optional array of numeric values containing
              the array elements to include in the expanded
              view.

<oParent> is the parent object for the tree-view.  This is usually
an XbpStatic or XbpTabPage object.  If no parent object is passed,
then an XbpDialog object will be created as the parent.

<aPos> is a 2-element array containing the pixel coordinates
of the starting location of the tree-view window.  Default is {0,0}

<aSize> is a 2-element array containing the width and height (in
pixels) of the tree-view window.  Default is {300,400}.

<cTitle> is the title of the Dialog Window.  This parameter is
ignored if <oParent> is a nil.

If <lHasButtons> is set to .T. (default), the tree view displays a
Plus or Minus sign at each node of the tree. This indicates whether
the next level of the tree can be expanded or suppressed.

If <lHasLines> is set to .T. (default), the tree view displays lines
between the nodes of the tree and their leaves. This results in a
more readable display.

Examples:

#INCLUDE "dcicon.ch"

FUNCTION Xtest()

LOCAL aDirectory, aDirOptions

aDirectory := Directory( '*.*' )
IF Len(aDirectory) > 50
  ASize(aDirectory,50)
ENDIF

aDirOptions := { { {|a,n|a[1]},         ;
                   ICON_CLOSEDFOLDER, ;
                   ICON_CLOSEDFOLDER, ;
                   ICON_OPENFOLDER }, ;
                 { {|a,n|FileData(a,n)}, ;
                   ICON_CLOSEDFOLDER, ;
                   ICON_CLOSEDFOLDER, ;
                   ICON_OPENFOLDER, ;
                   { 2,3,4,7,8 } } }

DC_GuiABrowse( aDirectory, aDirOptions, nil, nil, nil, ;
               'Directory of Files' )

RETURN nil

/* ------------------- */

STATIC FUNCTION FileData ( xData, nElement )

LOCAL cData := DC_XtoC( xData ), cPrefix

DO CASE
  CASE nElement = 2
    cPrefix := 'File Size: '
  CASE nElement = 3
    cPrefix := 'File Date: '
  CASE nElement = 4
    cPrefix := 'File Time: '
  CASE nElement = 7
    cPrefix := 'Creation Date: '
  CASE nElement = 8
    cPrefix := 'Creation Time: '
  OTHERWISE
    cPrefix := ''
ENDCASE

RETURN cPrefix + cData

Files:

_DCABROW.PRG, DCLIPX.LIB

See Also:

   @ DCTREEARRAY


dc_guiachoice()

A GUI replacement for ACHOICE()

DC_ACHOICE() is a Dual-mode replacement for AChoice(). When the GUI flag is ON, DC_ACHOICE() functions similiar to AChoice() except that it is displayed in GUI mode. When the GUI flag is OFF, DC_ACHOICE() functions identical to ACHOICE() except it is also activated by a mouse. The left button of the mouse is used to select the item in the window. The right button or double-clicking works identical to the ENTER key.<br><br> In TEXT mode, Hot keys can be activated by passing an array of screen coordinates (mouse-buttons) and key definitions.<br><br> In TEXT mode, an options array is used to define scroll-bars, colors, exit options, title, drag options, etc.<br><br> An optional array of Help-Codes may be passed for context- specific help on any selected item with the F1 key.

Syntax:

DC_GuiAChoice ( <nTop>, ;
                <nLeft>, ;
                <nBottom>, ;
                <nRight>, ;
                <aMenuItems>, ;
                [<aSelItems>], ;
                [<cUserFunc> | <bUserFunc>], ;
                [<nInitialItem>], ;
                [<nWindowRow>], ;
                [<cTitle>], ;
                [<aHelpCodes>], ;
                [<aMenu>], ;
                [<cFontName>], ;
                [@<oDlg>], ;
                [<lDestroy>], ;
                [<aMessage>], ;
                [<cHeader>],;
                [<lCenter>] ) -> nElement

Arguments:

<nTop>, <nLeft>, <nBottom>, <nRight> are the screen
coordinates in pixels.

<aMenuItems> is an array of character strings to include
in the pick-list.

<aSelItems> is an array of logical values.  There is one
element in this optional array for each element in
<aMenuItems>.  Each element in <aSelItems> that is a
.TRUE. will make the item in the window a "selectable"
item, otherwise it will be a non-selectable item and will
be displayed in "grayed" form.

<cUserFunc> | <bUserFunc> is the name of an optional User-Defined
function to call on exception keystrokes.  See the Clipper
documentation of ACHOICE() for more information on how to use
a UDF.  If the parameter is passed as a character string then
the function must be a PUBLIC, not STATIC function.

<nInitialItem> is the item to high-light in the window on
startup.

<nWindowRow> is the item to display as the first item in
the pick-list.

<cTitle> is the title of the window.

<aHelpCodes> is an array of character string HELP CODES.
There is one element in this optional array for each element in
<aMenuItems>.  The HELP CODE will be passed on to the
DC_HelpF1() function for context-specific help if the operator
presses F1 on a selected item.

<aMenu> is an array defining a Top-Bar/Pull-Down menu. This
array must conform to the specification for the array passed
to the DC_MENUMAIN() function.   This Top-Bar menu will be
painted at the screen coordinates defined in the menu if
<lAttachMenu> is .FALSE. or directly attached to the top of
the pick-list window if <lAttachMenu> is .FALSE. (default).
The menu will be energized if the operator presses a key
matching one of the hightlighted characters in the menu, or
if the mouse is clicked on one of the top-bar menu items.
The menu array must contain code-blocks for each menu item
to execute functions based on the menu selection.  See
DC_MENUMAIN() for more information.

<cFontName> is the name of an optional font.

@<oDlg> is a variable to store the dialog object for the
pick-list.

<lDestroy> if .TRUE. (default) will destroy the dialog
object for the browse.  If .FALSE., the dialog will remain
active.  Set this to .FALSE. when using DC_GUIACHOICE() in
a loop.

<aMessage> is an optional array of character strings to use as a
message to be displayed in the dialog window above the pick-list.

<cHeader> is an optional heading.

<lCenter> if .TRUE. will center the dialog in the display.

Examples:

Files:

_DCACHOI.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_achoice()


dc_guialert()

A GUI replacement for ALERT()

DC_GUIALERT() is a GUI replacement for Alert(). <br><br>

Syntax:

DC_GuiAlert( [<oOwner>], ;
             [<acText>], ;
             [<aCaption>], ;
             [<nSysIcon>], ;
             [<cTitle>], ;
             [@<aDlgPos>], ;
             [<lModal>], ;
             [<aFonts>]  ) -> nChoice

Returns:

 A numeric value equal to the button which was selected by the
 user.

Arguments:

<oOwner> is the owner of the dialog.  The default is
SetAppWindow().

<acText> may be a character string of text-lines (separated by
semi-colons) or an array of character strings for displaying
within the alert dialog above the button selections.

<aCaption> is an array of captions for buttons which will be
displayed in the dialog.  A tilde (~) character within the
caption text will underline the following character in the
push-button and make it the hot-key.  For example, '~Ok' will
underline the O in Ok and Alt-O will activate the button.

<nSysIcon> is the icon to display in the dialog.  This is a
numeric constant from XBP.CH.  The default is
XBPSTATIC_SYSICON_ICONQUESTION.

<cTitle> is the title to display in the title area of the dialog
window.

@<aDlgPos> is a numeric variable to store a two-element array
of coordinates which will be returned when the user exists the
alert window.  These coordinates are the screen coordinates of
the dialog before it was destroyed.  These coordinates may be
passed to DG_GUIALERT() again later to paint the dialog window
in the same location.

<lModal> if .TRUE. (default), will set the modal state of the
dialog window to APPMODAL.

<aFonts> is a 2-element array containing the Font Compound Name
for the buttons and the text.  Element 1 is the button font and
element 2 is the text font.

Notes:

The foreground and background color of the GUI alert box ispreset by the function DC_AlertColor().

Examples:

Files:

_DCMENU2.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_alert()


dc_guialertcolor()

Preset the foreground/background color of DC_GuiAlert()

DC_GUIALERTCOLOR() is used to establish the foreground and background color of the GUI alert box painted by the functions DC_Alert() in GUI mode and DC_GuiAlert().<br><br>

Syntax:

DC_GUIAlertColor( [<aColor>] ) -> aOldColor

Returns:

An array containing the previously set colors.

Arguments:

<aColor> is an array of two colors.  Element 1 is the foreground
color and element 2 is the background color. These may be
numeric colors defined by GRA_CLR_* constants in GRA.CH or they
may be 3-element arrays containing numeric RGB colors.

Examples:

DC_GUIAlertColor( { GRA_CLR_WHITE, GRA_CLR_RED } )

DC_Gui(.t.)

DC_Alert('This is a test')

Files:

_DCMENU2.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_alert()
   dc_guialert()


dc_guigrumpbrow()

An emulation of Greg Lief's GrumpBrow()

DC_GUIGrumpBrow() is an emulation of the GrumpFish function GrumpBrow() originally written for Clipper 5.x. It is full GUI and is based on the eXPress++ DC* command set rather than Tbrowse().<br><br>

Syntax:

The first 32 parameters are identical to the parameters used by
GrumpBrow().  Some of these parameters are not used either because
they have not yet been implemented or because they do not apply to
the GUI version.

DC_GUIGrumpBrow( [ <cSecurity>, ;
                   <nTop>, ;
                   <nLeft>,  ;
                   <nBottom>, ;
                   <nRight>, ;
                   <lBox>, ;                // not used
                   <aFields>, ;
                   <aHeads>, ;
                   <aPictures>, ;
                   <aAlternates>, ;
                   <xLow>, ;
                   <xHigh>, ;
                   <bVertical>, ;           // not used
                   <bHorizontal>, ;         // not used
                   <aExtraOptions>, ;
                   <nExtraOptionsKey>, ;
                   <cExtraOptionsTitle>, ;
                   <nExitKey>, ;
                   <aIndexDescriptions>, ;
                   <aValids>, ;
                   <aWhens>, ;
                   <nAutoRefresh>, ;
                   <nLockedColumns>, ;
                   <lCarry>, ;
                   <nMemoWidth>, ;
                   <cTitle>, ;
                   <nMemoHeight>, ;
                   <cColorSpec>, ;          // not used
                   <aColorBlocks>, ;
                   <bInitial>, ;
                   <lGoTop>, ;
                   <aAlternateKeys>, ;
                   <aPresParam>, ;
                   <aColWidths>, ;
                   <aEditCoords>, ;
                   <acMenu>, ;
                   <cBrowFont>, ;
                   <lResize>, ;
                   @<aGrumpGetList>, ;
                   <lModal>, ;
                   <oParent>, ;
                   <oAppWindow> ] ) -> cOptions

Arguments:

All Parameters are optional.

<cSecurity> is a string defining the security level you want to give
your users.  Case is not significant. You pass the first letter of
each feature that you wish to activate:

  A    Add
  E    Edit
  D    Delete
  P    Screen Painter // not supported
  Q    Query by example
  S    Search*
  V    View
  N    do Not allow individual field edit (see below)
  C    allow cell (individual field edit) only (no full-screen)
  K    allow user to pack the database
  I    allow user to swap index with ALT-I
  L    allow user to lock column with "L"
  F    allow user to "filter" (show data subset) with ALT-S
  O    output (print) all or some records (can be overridden
         as item #8 in <aAlternates>... see below)

 If you do not pass this parameter, all the user will be able to do is
 browse vertically and Esc when they are finished.

 *If no index file is open, or if the index key is not of character
 type, you will not be able to Search, regardless of whether or not
 you pass an "S" in <cSecurity>.

<nTop>, <nLeft>, <nBottom>, <nRight> delineate the screen region to
be used for the browse.  The default values are 0, 0, 24, and 79,
respectively.

<lBox> is ignored.

<aFields> contains character strings holding the names of the
fieldnames to show in the browse. Skip this parameter entirely if
you want to show all fields in the currently active database.

 SPECIAL NOTE: you can alternatively put code blocks in <aFields>
 to show any valid Xbase++ expression.  Note that any such columns
 will not be editable unless they are Get/Set code blocks.  These
 code blocks can be used for just about anything, including fields
 in databases other than the currently active work area.  You may
 also wish to make these code blocks "get-set", which means that
 they can assign values.  For example, the following code block
 displays the CUST->LASTNAME field and allows the user to edit it
 as well:

    { | x | if(x == NIL, cust->lastname, cust->lastname := x) }

<aHeads> contains column headings to be used for the browse.  If you
do not pass this, the fieldnames will be used as column headings.
Skip this parameter if you do not wish to use it. NOTE: No default
heading will be provided for columns that are based on code blocks
(see <aFields> description above).

<aPictures> contains PICTURE clauses corresponding to each field.
You may use this if, for example, you wish to truncate certain
fields or use "Y" for logicals.  If you do not pass this parameter,
DC_GuiGrumpBrow() will establish default PICTURE values for each
field that conform to the general norm.  Use a null string if you
do not wish to use this parameter.

<aAlternates> is an eight element array which is used to override
the default add/edit/etc. routines.  This array should be eight
elements long, and each element should contain either a code block
or a NIL.  The elements correspond to the actions as follows:

 aAlternate[1] = ADD function
 aAlternate[2] = DELETE function
 aAlternate[3] = EDIT function
 aAlternate[4] = QUERY function
 aAlternate[5] = SEARCH function
 aAlternate[6] = VIEW function
 aAlternate[7] = CELL EDIT codeblocks (see below)
 aAlternate[8] = OUTPUT function

 You only need to fill the elements that you wish to use. For
 example, if you want to use your own Add and Edit routines, you
 could do the following:

 LOCAL aAlternate[8]
 aAlternate[1] = { || SpecAdd() }
 aAlternate[3] = { |b| SpecEdit(b)}

 When the user presses "A" to Add or "E" to Edit, DC_GuiGrumpBrow()
 would evaluate these blocks and call SpecAdd() or SpecEdit(),
 respectively.  Note that the second code block accepts a parameter
 and passes it directly to SpecEdit().  This takes advantage of the
 fact that DC_GuiGrumpBrow() will automatically pass the Browse
 object and GetList to your alternate functions.  You can therefore
 manipulate the object as desired (e.g., resizing the window,
 forcing a manual refresh, etc).

 The seventh element of ALTERNATES array can contain an array
 containing code blocks for the columns where alternate cell editing
 is necessary.

 <xLow> and <xHigh> allow you to restrict browsing operations
 to a subset of records, ie a SCOPE.  These parameters may be of any
 data type -- conversion will be handled internally by
 DC_GuiGrumpBrow(). Note that the subset feature works only if you
 have an index file open!  Further note that if you have two indexes
 open, and wish to switch between them using ALT-I,
 DC_GuiGrumpBrow() will maintain a different data subset for each
 index.

 <bVertical> and <bHorizontal> are ignored.

<aExtraOptions> contains additional options which can be
accessed as a pop-up menu from within Grumpbrow().  The default key
to pop up this menu is ALT-F10, although this can be changed.

Create an array that contains nested arrays, each of which contains
the menu option as the first element and the code block to be
executed as the second element.  For example:

 { ;
    { "First option",  { || firstfunc() }     }, ;
    { "Second option", { || secondfunc() }    }, ;
    { "Third option",  { | a,b | thirdfunc(a,b) } }  ;
 }

Note that the third code block accepts a parameter and sends it
through to the function.  This is because DC_GuiGrumpBrow() will
pass the Browse object and GetList as parameters to your code
blocks when it evaluates them.  Therefore you can write your code
blocks in this fashion to access the Browse object and manipulate
it as you see fit.

<nExtraOptionsKey> can be used to override the default (ALT-F10)
key to pop up the additional options menu.

<cExtraOptionsTitle> will be used as the title for the pop-up
menu window.  By default, no title will be used.

<nExitKey> allows you to use a different key for exiting the
browse. Pass the INKEY value of the desired key as this parameter.
The default is K_ESC.  If you wish to allow multiple exit keys, you
may pass an array containing the desired INKEY values as this
parameter (or in conjunction with the EXITKEY clause of the
GRUMPBROW user-defined command).

<aIndexDescriptions> contains descriptive character strings for
each active index.  If you pass this parameter, these descriptions
will be displayed on the top row when users switch between indexes
with ALT-I.  Otherwise, the regular indexkey will be displayed.

<aValids> and <aWhens> allow you to attach VALID and WHEN
clauses to any or all columns in the browse.  If you use these, you
must use code blocks, and I would recommend generic coding to take
advantage of the GET object being passed as a parameter (e.g.,
{ |o| !empty(o:editBuffer()) }).  Note that these will apply to
both single-field and full-screen editing, as well as adding new
records.

<nAutoRefresh> is ideal for multi-user programs.  If you pass a
numeric expression as this parameter, DC_GuiGrumpBrow() will
automatically refresh the screen as often as you specify. Your
parameter represents the number of seconds.

<nLockedColumns> is a numeric indicating how many columns should
be locked from the outset.  By default this will be zero.

<lCarry> enables the values from the current record to be
carried forward as the defaults for new records.  Pass a logical
True if you want this behavior.

<nMemoWidth> is a numeric indicating the width to use for memo
windows.  By default, this will be either 40 or the width of the
browse window, whichever is smaller.

<cTitle> is a character string to be centered on the top row of
the DC_GuiGrumpbrow() window.  By default, no title will be used.
<nMemoHeight> is a numeric indicating the height to use for memo
windows.  By default, this will be eight rows.

<cColorSpec> is ignored.

<aColorBlocks> allows you to initialize the colorBlock instance
variable for one or more columns within the browse. This array
should contain either code blocks or NILs.

<bInitial> will be evaluated just prior to the browse being
displayed.  This allows you to manipulate the browse object (e.g.,
changing the separators, changing the defColor instance variable for
one or more columns, moving the cursor to some column other than the
first, etcetera). Your codeblock should be structured to accept one
parameter, which will be the browse object.

<lGoTop> enables you to force DC_GuiGrumpBrow() to move to the top
of the database each time that the user presses ALT-I to cycle
through the active indexes.  Pass .T. if you desire this behavior.
By default, the record pointer will remain unchanged, unless a data
subset has been established for the index you are switching to, in
which case the record pointer will be moved to the first record in
said subset.

<aAlternateKeys> can be used to override the default keys listed
below for each DC_GuiGrumpBrow() behavior. This array would contain
nested arrays which correspond to the following actions:

    Element   Action     Default Key    Default Message
    aKeys[1]  ADD             A         [A]dd
    aKeys[2]  DELETE          D         [D]elete
    aKeys[3]  EDIT            E         [E]dit
    aKeys[4]  QUERY           Q         [Q]uery
    aKeys[5]  SEARCH          S         [S]earch
    aKeys[6]  VIEW            V         [V]iew
    aKeys[7]  (n/a)
    aKeys[8]  OUTPUT          O         [O]utput
    aKeys[9]  LOCKCOLUMN      L         [L]ock
    aKeys[10] SUBSET          Alt-S     [Alt-S]ubset
    aKeys[11] SWAPINDEX       Alt-I     [Alt-I]ndex
    aKeys[12] PACK            K         pac[K]

The structure of each nested array is { <nInkeyValue>,
<cPrompt> }. If you do not need to change a particular key,
simply leave that array element NIL.

If you do not want to have any key tooltips displayed, simply pass
NIL as the second element of each nested array.

<aPresParam> is an array of presentation parameters for the
browse object.  See the Xbase++ documentation for the XbpBrowse()
class for a specification of this array.

<aColWidths> is an array of numeric values for each browse
column, one for each element of <aFields>.  For automatic sizing
insert a NIL in the array.

<aEditCoords> is an array of coordinates that defines the location
of the SAY (Header) prompt and GET (data) of each item in <aFields>
when using the full-screen editor.  Each element of <aEditCoords> is
a sub-array of 7 elements:

 <aEditCoords> element  Type     Description
 ---------------------  -------  --------------------------------
          1             Numeric  SAY (Header) Start Row
          2             Numeric  SAY (Header) Start Column
          3             Numeric  SAY Size (columns) default is 25
          4             Numeric  SAY Options - XBPSTATIC_TEXT_*
          5             Numeric  GET (Data) Start Row
          6             Numeric  GET (Data) Start Column
          7             Numeric  GET Size (columns) default is
                                 field width

<acMenu> is a Menu array or menu name that conforms to the
specifications for DC_MenuEdit().

<cBrowFont> is the font style for the browse.  This is a character
string that must conform to a standard Xbase++ font declaration,
ex: "8.Arial".  The default is "8.Courier".

<lResize> is reserved for future implementation.

@<aGrumpGetList> is the name of a variable, passed by reference,
to store a pointer to the GetList of the Grump dialog.

<lModal> if .TRUE. will cause the dialog window to be modal,
otherwise it will be modeless.

<oParent> is a reference to a parent dialog or to a memory
variable to store a reference to the dialog that will be
created.  If <oParent> has already been created as an Xbase Parts
class object, it will become the parent for all the objects in
the GetList.  If <oParent> is passed by reference as a NIL, the
dialog object created by the reader will be stored in this
memory variable.  NOTE: Xbase++ does not allow <oParent> to be
a PRIVATE or a PUBLIC variable if it is passed by reference.

The parent of the dialog that will be created is referenced by
APPWINDOW <oAppWindow>.  If no <oAppWindow> argument is used
then the parent of the created dialog will be AppDeskTop().

Notes:

MEMO SUPPORT

Memofields are shown in the browse window as "<memo>". To view amemo, highlight it and press Enter.

When adding, editing, or doing a query by example, you will noticethat memo support is handled quite neatly. As you go through the GETlist, when you hit a memo, a small window will open for you to editthe memo.

SECURITY LEVELS

You may define different security levels at different parts of the program. For example, you might want to give your users the abilityto add and edit records at one part of the program, but only view records elsewhere.

SEARCH

If you press "S" to search, and if the current controlling index isof character type, you may jump quickly to records by typing in thefirst few letters of the desired value. For example, searching forthe name 'MCALLISTER' could prove quite tedious in a 750-recorddatabase, but with quick-search you need only type in the letters"M", "C", and "A" to narrow the scope down considerably. As lettersare added to the search string, it is redisplayed centered along thebottom row of the browse box (unless the new letter results in avalue that is not FOUND() in the database). You may press backspaceto erase the rightmost character of the search string.

SWAPPING INDEXES (Alt-I)

If you have two index files open, you may switch between them bypressing Alt-I. This means that you could have one index on companyname and another on last name, and jump back and forth between themfor searches.

QUERY BY EXAMPLE

By pressing "Q" you can do a query-by-example to find the nextrecord matching their specific criteria. All you need do is fill inthe blanks. Fill in as many fields as you want to narrow the searchcriteria. Note that all query-by-example searches arecase-insensitive.

If you want to search for a field that contains a certain value, theymay enter that value surrounded by two periods ("..") on either side.For example, if you wanted to find the next record that contains theword "STREET" in the address field, you could enter "..STREET.." forthat field.

After you perform a query-by-example, the next time you press "Q" youwill be given the option to repeat the search using the same criteria(which will save you the bother of re-entering it).

SCREEN PAINTER

The screen painter will be supported in a future version

EDITING ONE FIELD

When the user highlights a field and press Enter, they can edit itdirectly without going to a vertical view. (This assumes, ofcourse, that you have given them Edit privileges.) If they wish toedit the same field in a series of records, they can terminate theREAD by pressing the down arrow, which will move them down onerecord and pop them immediately into edit mode.

However, there may be situations when you do not want the user to beable to edit an individual field. In such situations, you shouldinclude "N" as part of the security parameter.

By the same token, there may be situations where you only wantthe user to be able to edit individual fields (as opposed to afull-screen edit). This would apply if you had a number of codeblock (and thus non-editable) columns. In such situations, youshould include "C" (and not "N") as part of the security parameter.

Files:

_DCGBROW.PRG, DCLIPX.DLL

See Also:

   DCGRUMPBROW


dc_guimemoedit()

A GUI replacement for MemoEdit()

DC_GuiMemoEdit() is a GUI replacement for MemoEdit() that functions similiar to MemoEdit() except that it is displayed in GUI mode with extra buttons for Save and Abort and a line/column counter. <br><br> DC_GuiMemoEdit() recognizes both the XbpMLE() set of editing keys (Windows standard) and the MemoEdit() set of editing keys (WordStar standard).

Syntax:

DC_GuiMemoEdit( <cMemo>, ;
             <nTop>, ;
             <nLeft>, ;
             <nBottom>, ;
             <nRight>, ;
             <lEditMode>, ;
             <bcUserFunc>, ;
             <nLineLen>, ;
             <nTabSize>, ;
             <nBufferRow>, ;
             <nBufferCol>, ;
             <nWindowRow>, ;
             <nWindowCol>, ;
             <cTitle> ) -> cMemo

Returns:

 A Character String.

Arguments:

<cMemo> contains a character string or the contents of a memo
field. This character string is copied into the text buffer for
DC_GuiMemoEdit() and can then be displayed and/or edited. When <cString> is not specified, MemoEdit() begins with an empty text buffer.

<nTop> is an integer numeric value specifying the top screen row
at which the edit window is displayed by DC_GuiMemoEdit(). The four
arguments <nTop> , <nLeft> , <nBottom> and <nRight> determine the
screen coordinates for the edit window. Row positions for the
window can range from zero to MaxRow() and column positions can
range from zero to MaxCol().

<nLeft> is an integer numeric value specifying the left screen
column for the edit window display. The default value is zero.

<nBottom> is an integer numeric value specifying the bottom row
for the edit window display. The default value is MaxRow().

<nRight> is an integer numeric value specifying the right screen
column for the edit window display. The default value is MaxCol().

<lEditMode> is used to select either the edit or the display mode.
If .T. (true) is specified, the text buffer can be edited. When the
value .F. (false) is specified for <lEditMode> , the text buffer is
displayed and the user can only browse (not edit) the text buffer.
The default value is .T. (true).

<bcUserFunc> can contain a code block, a character string with the
name of a user-defined function or the value .F. (false). When
<bcUserFunc> contains a code block, it is executed after each keypress
not processed by DC_GuiMemoEdit(). Similarly, when the function name of a
user function is passed as a character string (without parentheses),
this function is called after each keypress not processed by
DC_GuiMemoEdit(). If a function name is specified, the function must not
be declared STATIC. A code block, however, can call a
STATIC FUNCTION.  Only the following keys will activate the evaluation
of <bcUserFunc>: F1 thru F12, Ctrl-F1 trhu Ctrl-F12, Alt-F1 thru Alt-F12,
Alt-A thru Alt-Z.  Two parameters are passed to the code block:
(1) the key value pressed, (2) a pointer to the XbpMle() object used as
the memo editor.

The argument <nLineLen> specifies the length of a line where
DC_GuiMemoEdit() automatically performs a word wrap. When <nLineLen> is
greater than the width of the edit window and an attempt is made
to move the cursor past the window border, the text is scrolled
horizontally. <nRight> - <nLeft> is used as the default value
for <nLineLen> .

<nTabSize> specifies the number of blank spaces inserted into the
text when the tab key (K_TAB) is pressed. By default four blank
spaces are inserted by K_TAB.

<nBufferRow> is an integer numeric value specifying the text row
where the cursor is positioned when MemoEdit() is called. The value
range for <nBufferRow> is from one to the entire number of rows in
<cString> . The default value is one. <nBufferRow> and <nBufferCol>
position the cursor within the text buffer, while <nWindowRow> and
<nWindowCol> determine the initial position of the cursor in the
edit window.

<nBufferCol> is an integer numeric value indicating the column
within the text row specified by <nBufferRow> where the cursor is
positioned when DC_GuiMemoEdit() is called. The value range for
<nBufferCol> is from zero to <nLineLen> . The default value is
zero.

<nWindowRow> specifies the row within the edit window where the
cursor is positioned when DC_GuiMemoEdit() is called. The value range
for <nWindowRow> is from zero to <nBottom> - <nTop> . The default
value is zero.

<nWindowCol> specifies the column within the edit window where the
cursor is positioned when DC_GuiMemoEdit() is called. The value range
for <nWindowCol> is from zero and to <nRight> - <nLeft> . The
default value is zero.

<cTitle> is the title to display in the window.

Examples:

 USE Address NEW

 DC_GuiMemoEdit( Address->Memo, 5, 10, 20, 60, .F., .F.)

Files:

_DCMEMOE.PRG, DCLIPX.LIB

See Also:


dc_guipopcalc()

A popup, full-function calculator

DC_GUIPOPCALC() is a calculator that can be called from Xbase++ code or in a code-block via the POPUP clause in the DCSAY..GET command.

Syntax:

DC_GuiPopCalc( [<nValue>], ;
               [<nStRow>], ;
               [<nStCol>], ;
               [<cTitle>],;
               [<@lOK>], ;
               [<lModal>], ;
               [<bHelp>], ;
               [<lInteger>]) -> nValue

Returns:

 The value of the calculator accumulator (numeric).

Arguments:

<nValue> is the starting value to place in the accumulator.
If no value is passed then the STATIC value stored in memory
will be the default.

<nStRow> and <nStCol> are the start display coordinates.  If
no values are passed then the calendar will be displayed
relative to the current cursor position (in TEXT mode)
or in the center of the screen (in GUI mode).  These coordinates
are text-based coordinates based on a home position of 0,0.
In GUI mode they are automatically converted to GUI-based
coordinates.

@<lOk> is a logical variable, passed by reference.  If the user
exits with an ABORT or ESCAPE, the variable will contain a
.FALSE., otherwise it will contain a .TRUE.

<cTitle> is the title in the titlebar area of the calculator.

<lModal> if .TRUE. (default) will make the dialog window modal,
otherwise it will be modeless.

<bHelp> is a code block that is evaluated when the user presses
the F1 key or clicks on the HELP button.

<lInteger> if .TRUE. will display the calculator accumulator without
decimals.

Examples:

 #include "dcdialog.ch"

 FUNCTION XTest()

 LOCAL GetList := {}, nNumber := 1234.56, oMsgBox

 DC_GUI(.t.)

 @ 1,1 DCSAY 'Enter Number' GET nNumber ;
  POPUP {|n|DC_GuiPopCalc(n)} ;
  MESSAGE 'Click on arrow for a calculator' ;
  INTO oMsgBox

 @ 3,1 DCMESSAGEBOX OBJECT oMsgBox SIZE 30

 DCREAD GUI FIT ADDBUTTONS

 RETURN nil

Files:

_DCCALC.PRG/.OBJ, DCLIPX.DLL

See Also:

   dc_popcalc()


dc_guipopdate()

A GUI pop-up calendar for selecting a date

DC_GUIPOPDATE() is a GUI calendar that can be called from Xbase++ code or in a code-block via the POPUP clause in the DCSAY..GET command.

Syntax:

 DC_GuiPopDate( [<dCurDate>],;
             [<nStRow>], ;
             [<nStCol>], ;
             [@<lOk>], ;
             [<cTitle>], ;
             [<lModal>], ;
             [<nStyle>], ;
             [<bHelp>], ;
             [<lHide>], ;
             [<lInstall>], ;
             [@<oDialog>], ;
             [@<aGetList>], ;
             [<bIsHoliday>], ;
             [<aColors>] ) -> dDate

Returns:

 The date selected.

Arguments:

<dCurDate> is the starting date to highlight in the calendar.
If no value is passed then the current system date will be
the default.

<nStRow> and <nStCol> are the start display coordinates.  If
no values are passed then the calendar will be displayed
relative to the current cursor position (in TEXT mode)
or in the center of the screen (in GUI mode).  These coordinates
are text-based coordinates based on a home position of 0,0.
In GUI mode they are automatically converted to GUI-based
coordinates.

@<lOk> is a logical variable (passed by reference).  This variable
will receive a .TRUE. if the user clicks on OK, double-clicks
on a date. or presses ENTER.  It will receive a .FALSE. if the
use clicks on ABORT or presses ESCape.

<cTitle> is the title in the Dialog Window.

<lModal> if .TRUE. (default) will make the dialog window modal,
otherwise it will be modeless.

<nStyle> is used to determine the style of the popup calendar.
This parameter is ignored in non-GUI mode.

  <nStyle>      Description
  ---------    ------------------------------------------------
      1         Large Calendar (original version)
      2         Small Calendar (with fancy buttons)
      3         Reserved.
      4         Small Calendar (without fancy buttons)

<bHelp> is a code block that is evaluated when the user presses
the F1 key.

If <lHide> is .TRUE., the calendar dialog is not destroyed when
exited. Instead it is hidden until DC_PopDate() is called again.
This provides the benefit of displaying the calendar instantly
after the first call to DC_PopDate().  The small calendar takes
longer to create because there are many more objects required
to handle the fancy buttons.  The default is .FALSE.

<lInstall> is used only with the <lHide> parameter.  It should
be passed as .TRUE. and used only once at the beginning of the
program in the main thread.  It installs the calendar as a
hidden calendar under the main thread to prevent lockups caused
by creating the hidden calendar in a different thread that is
later terminated.

@<oDialog> is a variable, passed by reference, to store a pointer
to the dialog window created by DC_PopDate().  This variable is
ignored if <nStyle> is 1 or <lHide> is .FALSE.

@<aGetList> is a variable, passed by reference, to store a
pointer to to GetList array used to create the calendar dialog.
This variable is ignored if <nStyle> is 1 or <lHide> is .FALSE.

<bIsHoliday> is a code block to evaluate to determine if a date
is a holiday.  This code block is called before painting each
date on the calendar.  The date is passed to the code block and
the code block must return a logical .T. if the date is a holiday
or a .F. if it is not a holiday.  Dates which are holidays are
displayed in the "holiday" color defined in the <aColors> array.
NOTE: this feature is available only in the "small calendar" -
style 2.

<aColors> is an array of 4 colors. Each element of the array is
a 2-element array containing a foreground and a background color
for the four different calendar colors.  See the below table.

Array Element     Description
-------------     -------------------------------------------
  [1]             Normal Color
  [2]             Today Color (Today's date)
  [3]             Passed-In Date Color
  [4]             Holiday Color

Example:

aColors := { ;
  { GRA_CLR_BLACK, GRA_CLR_WHITE }, ; // normal color
  { GRA_CLR_BLUE, GRA_CLR_WHITE }, ;  // today color
  { GRA_CLR_RED, GRA_CLR_WHITE }, ;   // passed date color
  { GRA_CLR_GREEN, GRA_CLR_WHITE }, ; // holiday color
}

Examples:

#include "dcdialog.ch"

FUNCTION XTest()

LOCAL GetList := {}, dDate := Date(), oMsgBox

@ 1,1 DCSAY 'Enter Date' GET dDate ;
  POPUP {|d|DC_GuiPopDate(d,,,,,,3)} ;
  MESSAGE 'Click on arrow for a calendar' ;
  INTO oMsgBox

@ 3,1 DCMESSAGEBOX OBJECT oMsgBox SIZE 30

DCREAD GUI FIT ADDBUTTONS

RETURN nil

 * ------------ Display Holidays ------------- *

FUNCTION XTest2()

LOCAL dDate := Date()+2, cTitle, lModal, bIsHoliday, nStyle, aColors

cTitle := 'Pick a Holiday'
bIsHoliday := {|d,x|x:=Dow(d)==1,x}
lModal := .T.
nStyle := 2

aColors := { ;
  { GRA_CLR_BLACK, GRA_CLR_WHITE }, ; // normal color
  { GRA_CLR_BLUE, GRA_CLR_WHITE }, ;  // today color
  { GRA_CLR_RED, GRA_CLR_WHITE }, ;   // passed date color
  { GRA_CLR_GREEN, GRA_CLR_WHITE }, ;           // holiday color
}

DC_GuiPopDate( dDate,,,,cTitle,lModal,nStyle,,,,,, ;
               bIsHoliday, aColors )

RETURN nil

Files:

_DCCALEN.PRG/.OBJ, DCLIPX.DLL

See Also:

   dc_popdate()


dc_helphandler()

Event handler for processing Help Requests

DC_HelpHandler() is used to send Help Requests from an eXpress++ application to the DC_Help() dialog window.<br><br>

Syntax:

 DC_HelpHandler( <nEvent>, ;
                 <mp1>, ;
                 <mp2>, ;
                 <oXbp>, ;
                 [<oDialog>], ;
                 [<aGetList>] ) -> nStatus

Arguments:

 <nEvent> is the event be processed.

 <mp1> is the first parameter of the event being processed.

 <mp2> is the second parameter of the event being processed.

 <oXbp> is a pointer to the object associated with the event
 being processed.

 <oDialog> is reserved.  No value needs to be passed.

 <aGetList> is a pointer to any GetList array in which associated
 events should not be processed.

Examples:

/*
In this example, all events from all windows created by DC_ReadGui()
will be passed on to DC_HelpHandler().
*/

DC_ReadGuiHandler({|a,b,c,d,e,f|DC_HelpHandler(a,b,c,d,e,f)})

Files:

_DCXHELP.PRG, DCHELP.DLL

See Also:

   dc_helpoptions()


dc_helpoptions()

Set Options for Help Window

DC_HelpOptions() is used to setup the Help System options. <br><br>

Syntax:

 DC_HelpOptions( [<aOptions>] ) -> aOldOptions

Returns:

 An array containing the previously set options.

Arguments:

 <aOptions> is an array of 13 elements.

 Array
 Element Type  Description
 ------- ----- ------------------------------------------------
    1      N   Hot key to View Focus Item info in window.
    2      N   Hot key to send Help Request for focus item
    3      B   Code block to enable hot keys
    4      B   Code block to enable help editing
    5     C/O  Font of Help Window
    6      C   Title of Help Window
    7      C   Help Root Name
    8      N   Help Type
    9      C   Help Database File Name
   10      O   Parent of Help Window
   11      N   Window Height (pixels)
   12      N   Window Width (pixels)
   13      C   Help Find Database File Name
   14      N   Help Exit Mode
               HELP_EXITMODE_HIDE - Hide window on exit
               HELP_EXITMODE_DESTROY - Destroy window on exit
               HELP_EXITMODE_QUIT - Quit application on exit
   15      C   Script files path
   16      C   HTML files path
   17      C   Temporary files path
   18      C   Help code of Glossary

Examples:

FUNCTION LoadHelpOptions( oDialog )

  LOCAL aHelpOptions[13]

  // Install global handler.
  DC_ReadGuiHandler({|a,b,c,d,e,f|DC_HelpHandler(a,b,c,d,e,f)})

  aHelpOptions[1]  := xbeK_ALT_F11    // Hot key to View Focus Item info in window
  aHelpOptions[2]  := xbeK_ALT_F1     // Hot key to send Help Request for focus item
  aHelpOptions[3]  := {||.t.}         // Code block to enable hot keys
  aHelpOptions[4]  := {||.t.}         // Code block to enable help editing
  aHelpOptions[5]  := '10.Courier'    // Font of Help Window
  aHelpOptions[6]  := 'XDEMO Help'    // Title of Help Window
  aHelpOptions[7]  := 'DESKTOP'       // Help Root Name
  aHelpOptions[8]  := 1               // Help Type
  aHelpOptions[9]  := 'HELP.DBF'      // Help Database Alias Name
  aHelpOptions[10] := oDialog:drawingArea // Parent of Help Window
  aHelpOptions[11] := 400             // Help Window Height
  aHelpOptions[12] := 620             // Help Window Width
  aHelpOptions[13] := 'HELPFIND.DBF'  // Help Find Database Alias Name
  DC_HelpOptions( aHelpOptions )

RETURN nil

Files:

_DCXHELP.PRG, DCHELP.DLL

See Also:

   dc_helphandler()


dc_hexstring2array()

Convert a hex string to a multi-dimensional array

DC_HexString2Array() will create an array from a hex string that was originally created by DC_Array2HexString().<br><br>This function is mainly intended for use on the internet when an array of information must be passed in an XML stream.<br><br><br><br>

Syntax:

DC_HexString2Array ( <cHexString> ) -> aArray

Returns:

An array.

Arguments:

<aArray> is any multidimensional array that contains variables of type
C, M, D, L, or N.

Files:

_DCASAVE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_array2hexstring()
   dc_ar2str()
   dc_asave()


dc_hexstringtovar()

Convert a Hex String to a Binary String

DC_HexString2Var() is used to convert hex strings to binary strings. Hex strings are used for storing in .TXT files or in memo fields that do not accept binary data.<br><br>

Syntax:

DC_HexString2Var( <cHexString> ) -> cBinaryString

Returns:

A Character String.

Arguments:

<cHexString> is a Hex String previously created by DC_Var2HexString().

Examples:

// Save Directory to a memo field
aData := Directory()
cData := DC_Var2HexString(Var2Bin(aData))
REPLACE CUSTOMER->directory WITH cData

// Restore Directory from a memo field
cData := DC_HexString2Var(CUSTOMER->directory)
aData := Bin2Var(cData)

Files:

_DCASAVE.PRG, DCLIPX.DLL

See Also:

   dc_var2hexstring()


dc_hmacsha1()

Returns a hash that meets SHA1 spec for encrypted message authentication

DC_HmacSha1() returns a hash that meets the RFC 2104 specification for encrypted message authentication.<br><br>See spec at http://www.ietf.org/rfc/rfc2104.txt<br><br><br><br>

Syntax:

DC_HmacSha1( <cKey>, <cMessage> ) -> <cHash>

Returns:

A string.

Arguments:

<cKey> is the key string.

<cMessage> is the message string.

Examples:

cHash := DC_HmacSha1( '^$%^$#','My Message' )

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_xorstrings()


dc_hourglassoff()

Turn off the HourGlass (wait) pointer

DC_HourGlassOn() cause the hourglass mouse pointer to be displayed until DC_HourGlassOff() is called.

Files:

DCLIPX.LIB, DCLIPX.DLL

See Also:

   dc_hourglasson()


dc_hourglasson()

Turn on the HourGlass (wait) pointer

DC_HourGlassOn() cause the hourglass mouse pointer to be displayed until DC_HourGlassOff() is called.

Files:

DCLIPX.LIB, DCLIPX.DLL

See Also:

   dc_hourglassoff()


dc_htmlgetvar()

Get the value of a variable from a web app var array

DC_HtmlGetVar() is used to extract the value of a variable from an array of variable definitions. This function is used in web-based applications that use Xb2.Net or the WAA adapter.

Syntax:

DC_HtmlGetVar( <aVars>, ;
               <cVarName>, ;
               [<lAnyCase>] ) -> cValue | NIL

Returns:

A character string if the variable is found in the array, otherwise
a NIL.

Arguments:

<aVars> is a 2-dimensional array containing variable names and
contents.  Each subelement must contain the following information:

Element  Type  Description
-------  ----  ----------------------------------------
  [1]      C   The variable name
  [2]      C   The variable contents

<cVarName> is the name of the variable to return.

<lAnyCase> if .TRUE. will find the variable regardless of case.
If .FALSE. (default) then <cVarName> must exactly match the name
in the <aVars> array.

Examples:

* ----- Xb2.Net example -----
#include "xb2net.ch"

aVars := {}
aVarList := oThread:getVar(nil,VAR_CONTENT)
IF Valtype(aVarList) == 'A'
  FOR i := 1 TO Len(aVarList)
    AAdd(aVars,aVarList[i])
  NEXT
ENDIF

aVarList := oThread:getVar(nil,VAR_QUERY)
IF Valtype(aVarList) == 'A'
  FOR i := 1 TO Len(aVarList)
   AAdd(aVars,aVarList[i])
  NEXT
ENDIF

cAddress1 := DC_HtmlGetVar( aVars, 'Address1' )
cAddress2 := DC_HtmlGetVar( aVars, 'Address2' )
cCity := DC_HtmlGetVar( aVars, 'City' )

* ----- WAA example -----

aVars := oHtml:Gateway():aQueryVars

cAddress1 := DC_HtmlGetVar( aVars, 'Address1' )
cAddress2 := DC_HtmlGetVar( aVars, 'Address2' )
cCity := DC_HtmlGetVar( aVars, 'City' )

Files:

_DCHTML.PRG, DCLIPX.DLL

See Also:

   dc_html()


dc_hunt()

Hunt for a record by search all indexes

DC_Hunt() is a method of Seeking a record by searching all open index files or tags for the value entered. This is the quickest method of finding information by scanning all the keys for the first match. The value entered is automatically converted to the proper "type" to perform the seek. For example, if you entered DC_Hunt(12.5), only numeric indexes will be seeked, or if you enter DC_Hunt('01/02/03'), only date indexes will be seeked. If you enter an expression, such as DC_Hunt('DATE()-30'), then only the indexes that match the type of the expression entered will be seeked.<br><br> Using DC_Hunt() is the fastest method of finding information in a large database that uses many index keys. It is recommended that you build a set of keys for all fields that you want to include in the DC_Hunt() operation. This can be accomplished easily by using the INDEX FIELDS command to create a set of tags all at one time.<br><br>

Syntax:

DC_Hunt( <cValue> | <cExpression>, ;
         [<lResume>], ;
         [<lDispMsg>] ) -> NIL

Returns:

 Nil.

Arguments:

<cValue> is the value to find.

<cExpression> is an expression that produces a value to find.

If no <cValue> | <cExpression> argument is passed, then the
user will be prompted to enter a value.

<lResume> if .TRUE. will resume "hunting" for an index starting
from the last index searched.  If .FALSE. (default) then the
"hunting" process starts at the first index in the order of
index files or tags.

<lDispMsg> if .TRUE. will display a message if record not found
(default).  IF .FALSe. will display no message - just leaves
file at EOF.

Notes:

HUNT automatically capitalizes the passed argument, so make sure that your character type indexes are UPPER() case. When building index tags with INDEX FIELDS, this is accomplished automatically.

Examples:

 . USE MAILLIST
 . INDEX FIELDS LAST, FIRST, COMPANY, MAIL_DATE, SOURCE ;
                TO MAILLIST.CDX
 . DC_Hunt('COMP')
 . DC_Hunt( nil, .t. )
 . DC_Hunt( DATE() )
 . DC_Hunt('LARRY')
 . DC_Hunt('EGGHEAD')

Files:

_DCHUNT.PRG, DCLIP2.DLL

See Also:

   HUNT


dc_icondefault()

Set Default Icon for Dialog Windows

DC_ICONDEFAULT() is used to establish a default ICON for Dialog Windows created by DC_ReadGui, DC_MsgBox() and other eXPress++ windows.<br><br>

Syntax:

 DC_IconDefault( [<nIcon>] ) -> nOldIcon

Returns:

 The previous icon (a numeric value).

Arguments:

<nIcon> is the numeric resource number of an icon that has
been linked into the .EXEcutable program.

Examples:

 #include 'dcicon.ch'

 FUNCTION XTest()

 LOCAL

 nOldIcon := DC_ICONDEFAULT(ICON_EXPRESS)

 DC_MsgBox('You should now see the eXPress++ Icon')

 DC_ICONDEFAULT(nOldIcon)  // Restore old icon

 RETURN nil

Files:

_DCMSG.PRG/.OBJ, DCLIPX.DLL

See Also:

   DC_ReadGui()
   DC_MsgBox()


dc_ifelse()

Evaluate a list of expressions based on a condition

DC_IFELSE() is a "function" replacement for IF...ELSE...ENDIF programming structure to be used when a function is needed, i.e. for calling via macro, code blocks, etc.<br><br>

Syntax:

 DC_IfElse ( <bIf>, ;
             <bDoIf>, ;
             [<bDoElse>] ) -> NIL

Returns:

 Nil.

Arguments:

<bIf> is a code block to be that is evaluated as the IF
statement.

<bDoIf> is a code block that is evaluated if <bIf> evaluates
.TRUE.

<bDoElse> is a code block that is evaluated if <bIf> evaluates
.FALSE.

Examples:

 . USE COLLECT
 . bIf := { || eof() }
 . bDoIf := { || DC_MsgBox("End of File") }
 . bElseIf := { || dbSkip() }
 . SetKey( -1, { || DC_IFELSE( bIf, bDoIf, bElseIf ) } )

Files:

_DCEVAL.PRG, DCLIP1.DLL

See Also:

   dc_docase()
   dc_dowhile()


dc_impl()

Implode a dialogue window created by dc_expl()

DC_IMPL() is used to implode a window created by DC_EXPL().

Syntax:

DC_Impl( [<aSaveScreen>] ) -> NIL

Returns:

 NIL

Arguments:

<aSaveScreen> is an array of screen information that was
originally returned by DC_EXPL().  If no parameter is
passed, then the static array posted by the last usage of
DC_EXPL() or the DCEXPLODE command will be used for the
screen information.  If no call to DC_EXPL() or DCEXPLODE
is made since the last call to DC_IMPL() or DCIMPLODE,
then the text is written to the CRT window and treated as
a normal @..SAY.

Examples:

 -- Example 1 --

 aSaveScreen := dc_expl( 10,10,12,70, ' Enter a command ' )
 cCommand := SPACE(50)
 @ 11,12 get cCommand
 read
 DC_IMPL( aSaveScreen )

 -- Example 2 --

 aSaveScreen :=  ;
     dc_expl( 10,10,15,70,'A Gui SAY Window',,,,,,.t. )
 dc_say(aSaveScreen,2,5,'This is 3/5')
 dc_say(aSaveScreen,4,10,'This is 4/10')
 DC_IMPL(aSaveScreen)

Files:

_DCEXPL.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_expl()


dc_implode()

Implode a window created by dc_explode()

DC_IMPLODE() is used to implode a window created by DC_EXPLODE().

Syntax:

DC_Implode( <cSaveScreen> ) -> nil

Arguments:

<cSaveScreen> is a composite string consisting of the screen
contents, coordinates, colors, etc.

Examples:

 cSaveScrn := dc_explode(5,10,7,70,'B/W','N/W',.F.,;
              ' Enter a Command ',10)
 cCommand := space(50)
 @ 6,12 get cCommand
 read
 DC_IMPLODE( cSaveScrn )

Files:

_DCEXPL.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_explode()
   dc_impl()
   dc_expl()
   dc_explmode()


dc_indexfilt()

Return the Conditional Index Expression

DC_INDEXFILT() returns the filter condition (if any) used in an open index.

Syntax:

DC_IndexFilt ( [<nOrder>] ) -> cExpression

Returns:

 A character string.

Arguments:

<nOrder> is the index order.  If no argument is given, then the
currently selected order is used.

Examples:

 . use sales via 'DBFNTX'  // Use Conditional Index driver
 . index on year for sales > 100000
 . ? DC_INDEXFILT()
 sales > 100000

 . select 2
 . use customer via 'DBFSIX'
 . index on cust_nmbr tag users of customer for cust_code = 'U'
 . ? DC_INDEXFILT()
 cust_code = 'U'

Files:

_DCAREA2.PRG/.OBJ, DCLIPX.LIB

See Also:


dc_indexkey()

Return the current index key expression

DC_INDEXKEY() is used as a replacement for Clipper's INDEXKEY() function to prevent runtime errors when using a database driver that does not suport indexes.

Syntax:

DC_IndexKey () -> cKeyString

Returns:

 A Character string containing the current index key value.
 If no index is in use or a data driver is being used that
 does not support indexes, then a null "" string is returned.

Arguments:

 None

Examples:

 use sales
 index on year+month to sales
 ? DC_INDEXKEY()
 year+month

Files:

_DCAREA2.PRG/.OBJ, DCLIPX.LIB


dc_iniload()

Load an array from a *.INI (initialization) file

DC_INILOAD() is used to populate an array with the contents of an initilization group in a *.INI file. *.INI files are used by Windows 3.1 for initialization of various sub-systems and applications and have become a defacto-standard for initialization systems.

Syntax:

DC_IniLoad( <cIniFile>, ;
            <cGroup>, ;
            <aArray>, ;
            <aReference> ) -> lStatus

Returns:

 A logical .TRUE. if the file exists, if the <cGroup> can
 be found in the file and if at least one element of the
 array was updated from the file, .FALSE. otherwise.

Arguments:

<cIniFile> is the name of the *.INI file to load.  If the full
path is not included in the file name, then it is assumed that
the file must exist in the same directory as the .EXEcutable
program or in the directory established by the SET DCLIP=<path>
command in your AUTOEXEC.BAT file.

<cGroup> is the Group Name you wish to load.

<aArray> is the array to populate from the contents of the
intialization group.  This array must already exist and must
contain default values for each item.  Values may be the
following types: (C)haracter, (N)umeric, (D)ate, (L)ogical.

<aReference> is a parallel array that contains the same number
of elements as <aArray>.  This array contains the name of each
intialization item for each item in <aArray>.

Notes:

<aArray> should be already populated by default values. If there is no item in the *.INI file that matches a specified element of the array, then its value will not be changed.

Examples:

/* Sample *.INI file */

* MYCOLORS.INI

[COLORSET_1]
ColorSet=Standard Color Set
DotPrompt=W+/B
StatusLine=N/W
StatusData=N/W

[COLORSET_2]
ColorSet=Color Set #2
DotPrompt=GR+/GR
StatusLine=N*/N
StatusData=W+*/N

/* -- Example 1  (Loading an array from COLORSET_2 -- */

aRef := {'ColorSet','DotPrompt','StatusLine','StatusData'}

DC_INILOAD('MYCOLORS.INI','COLORSET_2',aColors[2],aRef)

Files:

_DCINI.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_inisave()


dc_iniread()

Read a parameter from a *.INI (initialization) file

DC_INIREAD() is used to read a specified parameter from an initialization (.INI) file.

Syntax:

DC_IniRead( <cIniFile>, ;
            <cGroup>, ;
            <cParamName> ) -> cValue

Returns:

 A character string.

Arguments:

<cIniFile> is the name of the *.INI file to load.  If the full
path is not included in the file name, then it is assumed that
the file must exist in the same directory as the .EXEcutable
program or in the directory established by the SET DCLIP=<path>
command in your AUTOEXEC.BAT file.

<cGroup> is the Group Name you wish to load.

<cParamName> is the name of the variable that belongs to the
group <cGroup>.  This name is case sensitive.

Examples:

/* Sample *.INI file */

* MYCOLORS.INI

[COLORSET_1]
ColorSet=Standard Color Set
DotPrompt=W+/B
StatusLine=N/W
StatusData=N/W

[COLORSET_2]
ColorSet=Color Set #2
DotPrompt=GR+/GR
StatusLine=N*/N
StatusData=W+*/N

/* -- Example  (Loading a var from COLORSET_2 -- */

cColor := DC_INIREAD('MYCOLORS.INI','COLORSET_2','DotPrompt')
SetColor(cColor)

Files:

_DCINI.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_iniwrite()
   dc_iniload()


dc_inisave()

Save an array to a *.INI (initialization) file

DC_INISAVE() is used to save an array with the contents of an initilization group to a *.INI file. *.INI files are used by Windows 3.1 for initialization of various sub-systems and applications and have become a defacto-standard for initialization systems.

Syntax:

DC_IniSave( <cIniFile>, ;
            <cGroup>, ;
            <aArray>, ;
            <aReference> ) -> lStatus

Returns:

 A logical .TRUE. if the initialization group was properly
 saved, FALSE otherwise.

Arguments:

<cIniFile> is the name of the *.INI file to save.  If the full
path is not included in the file name, then it is assumed that
the file must exist in the same directory as the .EXEcutable
program or in the directory established by the SET DCLIP=<path>
command in your AUTOEXEC.BAT file.  If the file does not exist
it will be created.  If it already exists, then only the GROUP
in the file that matches <cGroup> will be updated.

<cGroup> is the Group Name you wish to save.

<aArray> is the array to write to the initialization group.
This array may contain values of the following types:
(C)haracter, (N)umeric, (D)ate, (L)ogical.

<aReference> is a parallel array that contains the same number
of elements as <aArray>.  This array contains the name of each
intialization item for each item in <aArray>.

Examples:

/* Sample *.INI file */

* MYCOLORS.INI

[COLORSET_1]
ColorSet=Standard Color Set
DotPrompt=W+/B
StatusLine=N/W
StatusData=N/W

[COLORSET_2]
ColorSet=Color Set #2
DotPrompt=GR+/GR
StatusLine=N*/N
StatusData=W+*/N

/* -- Example 1  (Saving an array to COLORSET_2 -- */

aRef := {'ColorSet','DotPrompt','StatusLine','StatusData'}

DC_INISAVE('MYCOLORS.INI','COLORSET_2',aColors[2],aRef)

Files:

_DCINI.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_iniload()


dc_iniwrite()

Write a parameter to a *.INI (initialization) file

DC_INIWRITE() is used to write a specified parameter to an initialization (.INI) file.

Syntax:

DC_IniWrite( <cIniFile>, ;
             <cGroup>, ;
             <cParamName>, ;
             <xValue> ) -> lStatus

Returns:

 A logical .TRUE. if the value was stored properly.

Arguments:

<cIniFile> is the name of the *.INI file to load.  If the full
path is not included in the file name, then it is assumed that
the file must exist in the same directory as the .EXEcutable
program or in the directory established by the SET DCLIP=<path>
command in your AUTOEXEC.BAT file.

<cGroup> is the Group Name you wish to load.

<cParamName> is the name of the variable that belongs to the
group <cGroup>.  This name is case sensitive.

<xValue> is the value to store.  This may be any type however
it is stored as a character type.

Examples:

/* Sample *.INI file */

* MYCOLORS.INI

[COLORSET_1]
ColorSet=Standard Color Set
DotPrompt=W+/B
StatusLine=N/W
StatusData=N/W

[COLORSET_2]
ColorSet=Color Set #2
DotPrompt=GR+/GR
StatusLine=N*/N
StatusData=W+*/N

/* -- Example  (Saving a var to COLORSET_2 -- */

cColor := SetColor()
DC_INIREAD('MYCOLORS.INI','COLORSET_2','DotPrompt', cColor)

Files:

_DCINI.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_iniread()
   dc_iniload()


dc_inkey()

Moused replacement for INKEY()

DC_INKEY() is used to return the integer numeric value of a key pressed or mouse button. This is designed as a replacement for INKEY() when it is required that a procedure be called if a function key is pressed by the operator or a mouse is being used.<br><br> DC_INKEY() will evaluate any functions which have been previously established by the SET KEY command or SetKey() function.<br><br> DC_INKEY() is also designed for use with a context-specific help system and the procedures which have been loaded into function keys by the KEY LOAD command or DC_KEYLOAD().

Syntax:

DC_Inkey ( [<nSeconds>], ;
           [@<nMouRow>], ;
           [@<nMouCol>], ;
           [<lWaitRele>], ;
           [<lWinMode>], ;
           [<lGetReader>], ;
           [<lNoDblClick>], ;
           [<lDragMode>], ;
           [<cHelpCode>], ;
           [<aMouseHelp>] ) -> nInkeyValue

Returns:

 0 if no key is pressed before timeout.

 The numeric value of the key pressed (same as INKEY() )

 -101 if the left mouse button is pressed
 -102 if the right mouse button is pressed
 -104 if the right mouse button is released, the left
      mouse button is double-clicked, or the left mouse
      button in released when in "Windows" compatible
      mode.

Arguments:

<nSeconds> is the number of seconds to wait for a key press or
mouse click.  If 0 (default) then DC_INKEY() will wait forever.

@<nMouRow> and @<nMouCol> are memory variables passed by
reference to store the current row and column location of the
mouse if a mouse button is pressed.

<lWaitRele> if .TRUE. will wait until the mouse button is
released before processing any more mouse actions.  If this
parameter is not passed, then the last call to DC_INKEYRELE()
will establish the default mode.

<lWinMode> if .TRUE. will cause DC_INKEY() to behave more like
Windows programs. Normally, the right-button must be pressed
or the left-button double-clicked for DC_INKEY() to return a
-104 value.  If DC_INKEYWIN(.t.) is called in your setup
program and the <lWinMode> parameter is passed to DC_INKEY(),
then simply releasing the left button will return the -104 value
to invoke the menu selection.

<lGetReader> is reserved.

<lNoDblClick> if .TRUE. will disable mouse double-click from
returning a -104 but instead will return a -101 (same as single
click).  The default is .FALSE.

<lDragMode> if .TRUE. will return a value of 13 (K_ENTER) if
the left mouse button is pressed.  The default is .FALSE.

<cHelpCode> is a code of up to 22 characters to pass to the
DC_HELPF1() function in the event that the F1 or ALT-F1 keys
are pressed.

<aMouseHelp> is an array of information to display on the
screen if the mouse is moved over specified areas (icons) on
the screen.  This optional array allows for displaying of help
information when the mouse is placed over a screen area.  This
is a 2-dimensional array that consists of a sub-array of screen
coordinates for displaying the message and another sub-array
consisting of a sub-sub-array for each mouse icon area.

<aMouseHelp[1]> is defined as follows:

 Element   Type    Description
 -------   ---- -------------------------------------
   [1]      N      Start Message display row
   [2]      N      Start Message display column
   [3]      N      End Message display row
   [4]      N      End Message display column

<aMouseHelp[2]> contains one array for each icon and is defined
as follows:

 Element   Type    Description
 -------   ---- -------------------------------------
   [1]      N      Start Icon display row
   [2]      N      Start Icon display column
   [3]      N      End Icon display row (if element is a NIL
                   then element [1] is the default)
   [4]      N      End Icon display column (if element is a NIL
                   then element [2] is the default)
   [5]      C      Message to display when mouse is placed
                   over element 1-4 screen coordinates
   [6]      B      Optional code-block to disable the message
                   for this item.  Must return a logical .T.
                   to enable message or .F. to disable message.
                   The default is .TRUE.

Examples:

 local nRow, nCol

 set key -1 to myfunc1
 set key -2 to myfunc2

 // Call HELP("MYFUNC") if F1 is pressed
 // Call MYFUNC1() if F2 is pressed
 // Call MYFUNC2() if F3 is pressed
 nInkey := DC_INKEY( 'MYFUNC', 0, @nRow, @nCol )

Files:

_DCINKEY.PRG/.OBJ, DCLIPX.LIB

See Also:

   INKEY
   dc_inkeydsp()
   dc_tbinkey()


dc_inkeydsp()

Display Inkey() and AppEvent() values for pressed keys

DC_InkeyDsp() is used to display Inkey() and AppEvent() values for keys pressed by the user.<br><br>

Syntax:

 DC_InkeyDsp ( [@<nAppEvent>] ) -> nInkey

Returns:

 The numeric Inkey() value of the key pressed.

Arguments:

@<nAppEvent> is a variable (passed by reference) to store the
AppEvent() value of the key pressed.

Examples:

 . nAppEvent := 0
 . nInkey := DC_InkeyDsp(@nAppEvent)
 . ? nInkey, nAppEvent

Files:

_DCINKEY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_inkey
   INKEY


dc_inkeyeval()

Post a code block for evaluation by DC_INKEY()

Many dCLIP functions make calls to DC_INKEY() to get a key. If you post a code block with DC_INKEYEVAL() before calling dCLIP functions you can interrupt your application.

Syntax:

DC_InkeyEval ( <bBlock> ) -> bBlock

Returns:

 The last posted DC_INKEYEVAL() code block.

Arguments:

<bBlock> is a code block to evaluate.

Notes:

Examples:

 LOCAL nRow, nCol
 DC_INKEYEVAL( {||DevPos(0,0),DevOut(Time())} )
 nInkey := DC_INKEY( 'MYFUNC', 0, @nRow, @nCol )

Files:

_DCINKEY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_inkey()


dc_inkeyrelease()

Require mouse to be released or positioned in specified area

DC_INKEYRELEASE() is used to insure that DC_INKEY() will only return a value if the mouse button is released after a specified amount of time or if the mouse is within a specified area.

Syntax:

DC_InkeyRelease ( <nSeconds> ) -> nil

Returns:

 nil

Arguments:

If <nSeconds> is 0, then DC_INKEY() will return a value only
if the mouse button is released or the mouse is within the
passed coordinates.

If <nSeconds> is greater than 0 then DC_INKEY() will return
a value only after the specified amount of time .AND. if the
mouse is in the specified coordinates.  If coordinates are not
passed, then DC_INKEY() will return a value regardless of the
mouse position.

Files:

_DCINKEY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_inkey()


dc_inspectobject()

An Xbase Parts Object Inspector

DC_INSPECTOBJECT() is used to display and return the current status of any object that is derived from an Xbase Parts class. The contents of Instance variables (iVars), Slots (CallBacks) and Methods are displayed in three browse windows. <br><br> If the contents is a code block then the actual code block text will be displayed. <br><br> If the contents is an array, then the array contents will be displayed (up to a fixed length to prevent overflowing the display) and double-clicking the item in the browse will display the contents of the array using the array browser.<br><br> If the contents is an object, the classname of the object will be displayed and double-clicking the item in the browse will display the contents of the object using the object browser.<br><br> If the contents is any other data type, the full value will be displayed.<br><br>

Syntax:

DC_InspectObject( <oObject>, ;
                  [<lDisplayResults>], ;
                  [@<aResults>] ) -> cResults

Returns:

 A Character string containing all the information delimited
 by Chr(13) + Chr(10) for display in a memo window.

Arguments:

<oObject> is any type of object that is derived from an Xbase
Parts class.

<lDisplayResults> (default) will display the results in three
browse windows.

@<aResults> is a variable, passed by reference, to return a
multi-dimensional array contains the inspection results.  This
is an array of 3 sub-arrays.

[1] Instance Variables
[2] Callback Slots
[3] Methods

Each sub-array contains an array for each item.

[1] Item name
[2] Item contents (character string equivalent)
[3] Information about item
[4] Item value

Notes:

CAUTION: Double-Clicking in the Methods window will call theassociated method and display it's returned value in a window.

Examples:

 PROCEDURE XTest()

 LOCAL oDialog

 oDialog := XbpDialog():new(AppDesktop(),,{100,100},{200,300})
 oDialog:create()
 DC_InspectObject(oDialog)

 RETURN

Files:

_DCARRAY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_arrayview()


dc_inspectobject2array()

Create an array containing iVar names and values of an object

DC_InspectObject2Array() is to create a multi-dimensional array that contains current status of any object that is derived from an Xbase class. The contents of Instance variables (iVars), Slots (CallBacks) and Method names will be contained in the array.<br><br> If the contents is a code block then the actual code block text will be written to the array. <br><br> If the contents is an object, the classname of the object will be written to the array.<br><br> If the contents is any other data type, the full value will be written to the array.<br><br>

Syntax:

DC_InspectObject( <oObject>, ;
                  [<lIncludeMethods>] -> aResults

Returns:

A Multi-Dimensional array.

Arguments:

<oObject> is any type of object that is derived from an Xbase
class.

<lIncludeMethods (default) will also include the names of
methods.

Examples:

 PROCEDURE XTest()

 LOCAL oDialog

 oDialog := XbpDialog():new(AppDesktop(),,{100,100},{200,300})
 oDialog:create()
 aArray := DC_InspectObject2Array(oDialog)
 DC_ArrayView(aArray)
 RETURN

Files:

_DCARRAY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_inspectobject()


dc_inspectobject2file()

Create a file containing iVar names and values of an object

DC_InspectObject2File() is to create a text file that contains current status of any object that is derived from an Xbase class. The contents of Instance variables (iVars), Slots (CallBacks) and Method names are contained in the file.<br><br> If the contents is a code block then the actual code block text will be written. <br><br> If the contents is an object, the classname of the object will be written.<br><br> If the contents is any other data type, the full value will be written.<br><br>

Syntax:

DC_InspectObject( <oObject>, ;
                  <cFileName>, ;
                  [<lIncludeMethods>] -> lStatus

Returns:

A logical .TRUE. if the file could be created, .FALSE. otherwise.

Arguments:

<oObject> is any type of object that is derived from an Xbase
class.

<cFileName> is the name of the file to create.

<lIncludeMethods (default) will also include the names of
methods.

Examples:

 PROCEDURE XTest()

 LOCAL oDialog

 oDialog := XbpDialog():new(AppDesktop(),,{100,100},{200,300})
 oDialog:create()
 lStatus := DC_InspectObject2File(oDialog,"C:\test\test.txt")

 RETURN

Files:

_DCARRAY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_inspectobject()


dc_inspectobjectevent()

Set the event which will invoke the Object Inspector

DC_INSPECTOBJECTEVENT() is a Get/Set function that is used to establish the event which will invoke the Object Inspector.<br><br>

Syntax:

DC_InspectObjectEvent( [<nEvent>] ) -> nOldEvent

Returns:

 A numeric value.

Arguments:

<nEvent> is any event that is pulled from the event queue.

Examples:

 #include "appevent.ch"

 // popup the object inspector when a right-button double-click
 // occurs on an object.
 DC_InspectObjectEvent( xbeM_RbDblClick )

Files:

_DCARRAY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_inspectobject()


dc_inspectthreads()

Pop up a browse with information about running threads

DC_InspectThreads() will popup a browse screen with information about currently running threads.<br><br>The browse consists of 4 columns of information about each thread.<br><brɭ. The Thread ID. 2. The Thread Handle. 3. The currently running procedure in the thread. 4. The currently running line number in the thread.<br><br>Double-click on an item in the browse to popup the thread object inspector.<br><br><br><br>

Syntax:

DC_InspectThreads() -> nil

Arguments:

None.

Examples:

The below code will cause Alt-F11 to popup the thread
inspector anywhere in the application.

DC_SetKeyActive(.t.)
SetKey(K_ALT_F11,{||DC_InspectThreads()})

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_inspectobject()


dc_interpret()

Interpret a command string

DC_INTERPRET() is a command-line interpreter that will translate and execute any sequence of commands that is supported by Xbase++, eXPress++ and/or any command that has been user defined in DCCUSTOM.CH. DC_INTERPRET() requires that the file DCSTD.CH and DCCUSTOM.CH exist in the INCLUDE path of the workstation. The DCSTD.CH file contains all the standard eXPress++ commands and pointers to the Xbase++ include files for the standard Xbase++ commands and defines.<br><br> DC_INTERPRET() will execute a single command string or an array of commands that encompass an entire procedure with passed parameters and a return value.<br><br> DC_INTERPRET() was designed to work in conjuction with DC_PROGRAM() and/or DC_PROGLOAD() which will load a program from the DCPROG.DBF program catalog, compile the program into a multi-dimensional array, then pass the program to DC_INTERPRET() for execution.<br><br>

Syntax:

DC_Interpret( <acCommands>|<cCommand>, ;
              [<aParams>] ) -> xReturnVal

Returns:

The return value of the program being interpreted.

Arguments:

<acCommands> is a string containing a set of commands or an
array containing a procedure.  If <acCommands> is an array,
then it must conform to the specifications of the array returned
by DC_PROGLOAD(). If this parameter is a NIL, then the Windows
ClipBoard will be used as the program to interpret.  This
allows for cutting code snippets out of a help file, copying
them to the ClipBoard and then interpreting the code snippet.

<aParams> is a single-dimensional array of parameters to pass
to the program being interpreted.  There should be one element
in the array for each parameter included in the PARAMETERS
statement in the interpreted program.

Examples:

 . DC_Interpret(MemoRead('MYPROG.TXT'))

Files:

_DCDOT.PRG

See Also:

   dc_dot()
   dc_translate()


dc_isanum()

Is a character alphanumeric?

DC_ISANUM() is used to test whether or not a character is an alphanumeric character: <br><br> ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz 0123456789

Syntax:

 DC_IsAnum (<cCharacter>) -> lStatus

Returns:

 A logical .TRUE. if the character is an alphanumeric character,
 .FALSE. otherwise.

Arguments:

<cCharacter> is a character string with a length of 1.

Examples:

 ? DC_IsAnum('Z')
 .T.

 ? DC_IsAnum('j')
 .T.

 ? DC_IsAnum('4')
 .T.

 ? DC_IsAnum('$')
 .F.

Files:

_DCVAL.PRG, DCLIPX.DLL


dc_isanychr()

Is any Character in A string also in B string

Tests for the existence of any character in string A also existing in string B.

Syntax:

DC_IsAnyChr( <cStringA>, <cStringB> ) -> lStatus

Returns:

A logical .TRUE. if any character in A also exists in B.

Arguments:

<cStringA> and <cStringB> are character strings.

Examples:

cStringA := 'Hello World'
cStringB := 'fox'

? DC_IsAnyChr( cStringA, cStringB )

.T.

Files:

_DCANYCH.PRG, DCLIPX.DLL


dc_isapprunning()

Test if an application is running

DC_IsAppRunning() is used to determine if an Xbase++ application is already running.

Syntax:

DC_IsAppRunning( <cClass>, ;
                 <cTitle>, ;
                 [<cFile>], ;
                 [<lRestore>] ) -> lStatus

Returns:

A logical .TRUE. if the application window is running, .FALSE.
otherwise.

Arguments:

<cClass> is the class name of the window.  This is usually
"XbpDialog".  If the application window is an XbpCrt() window,
then use the class name "XbpPmtClass".

<cTitle> is the title of the Window.

<cFile> is the file name of the Window.  If this parameter is
not use, then the <cTitle> parameter must be used.

<lRestore> if .TRUE. will set focus to the found application
window.

Examples:

// MYAPP.EXE

#INCLUDE "dcdialog.CH"

FUNCTION Main()

LOCAL GetList := {}, dDate := Date(), oDate

IF DC_IsAppRunning('XbpDialog',,'MYAPP.EXE',.t.)
  RETURN .f.
ENDIF

@ 0,0 DCSAY 'My Test Dialog' GET dDate POPUP {|d|DC_PopDate(d)} ;
   SAYSIZE 0 GETOBJECT oDate

DCREAD GUI FIT ADDBUTTONS TITLE 'Enter the Date' ;
   EVAL {|o|o:setInputFocus := {||SetAppFocus(oDate)} }

RETURN .t.

* -------------

PROC AppSys()
RETURN

Files:

_DCFUNCT.PRG, DCLIPX.DLL


dc_isblank()

Test to determine if all the fields in a record are empty

DC_ISBLANK() is used to report whether or not every field in the current record of the current workarea is empty.<br><br>

Syntax:

 DC_IsBlank() -> lStatus

Returns:

 A logical .TRUE. if the record is blank, .FALSE. otherwise.

Arguments:

 None.

Examples:

 . USE COLLECT
 . GO 5
 . ? DC_IsBlank()
.F.

Files:

_dcblank.prg, DCLIP1.DLL

See Also:

   BLANK
   dc_blank()


dc_isdescend()

Is the current index a Descending index?

DC_ISDESCEND() is used to report if the currently selected index is indexed in descending order. This function will only report correctly if the DESCEND option was used during indexing, not if the DESCEND() function was used.<br><br><br><br>

Syntax:

 DC_IsDescend( [<nOrder>] ) -> lStatus

Returns:

 A logical .TRUE. if the index is Descending, .FALSE. otherwise.

Arguments:

<nOrder> is the order number of the controlling index. If
no parameter is passed then the current controlling index
will be used.

Examples:

 use customer
 index on cust_name to custname
 ? DC_ISDESCEND()
 .F.
 index on cust_name to custname descending
 ? DC_ISDESCEND()
 .T.
 index on DESCEND(cust_name) to custname
 ? DC_ISDESCEND()
 .F.

Files:

_DCAREA.PRG, DCLIP1.DLL

See Also:

   dc_isunique()


dc_isdescendant()

Is an object a descendant of another object.

DC_IsDescendant() is used to determine if an object is a descendant of another object, ie a child, a grandchild, a great-grandchild, etc.

Syntax:

DC_IsDescendant( <oXbp>, ;
                 <oAncestor> ) -> lStatus

Arguments:

<oXbp> is the object to test.

<oAncestor> is the ancestor to test.

Files:

_DCFUNCT.PRG, DCLIPX.DLL


dc_isdir()

Does a directory exist?

DC_IsDir() is used to test if a directory exists.<br><br>

Syntax:

 DC_IsDir( <cDirectory> ) -> lStatus

Returns:

 A logical .TRUE. if the directory exists, .FALSE. otherwise.

Arguments:

<cDirectory> is the directory to test.

Files:

_DCPATH.PRG, DCLIPX.DLL

See Also:

   dc_pathfound()
   dc_path()


dc_ispath()

Is a directory listed in an Environment string?

DC_ISPATH() is used to test if a directory has been listed in a path string.<br><br>

Syntax:

 DC_IsPath ( <cPath>, ;
             <cDirectory> ) -> lStatus

Returns:

 A logical .TRUE. if the directory exists in the path string,
 .FALSE. otherwise.

Arguments:

<cPath> is a path string with drive/directories separated
by semicolons.

<cDirectory> is the directory to test.

Examples:

 ? DC_ISPATH( GETE('PATH'),'C:\DOS' )
 .T.

 SET(_SET_PATH,'C:\MYDATA;D:\HISDATA;D:\HERDATA')
 ? DC_ISPATH( SET(_SET_PATH), 'C:\HISDATA' )
 .T.
 ? DC_ISPATH( SET(_SET_PATH), '\WINDOWS' )
 .F.

Files:

_DCPATH.PRG, DCLIPX.DLL

See Also:

   dc_pathfound()


dc_isshared()

Is a work area opened in Shared mode?

DC_ISSHARED() is used to report whether a database in a specified work area was opened in SHARED mode or EXCLUSIVE.<br><br><br><br>

Syntax:

 DC_IsShared ( [<nArea>] ) -> lStatus

Returns:

 A logical .TRUE. if the file is open SHARED, .FALSE. otherwise.

Arguments:

<nArea> is the work area be queried.  If no argument is given,
then the current work area is default.

Examples:

 use customer shared
 ? DC_ISSHARED()
 .T.

Files:

_DCAREA.PRG, DCLIP1.DLL

See Also:


dc_isstru()

Verify the structure of a database

DC_ISSTRU() is used to verify that the current database matches a structure from an Xbase++ or eXPress++ structure array.<br><br><br><br>

Syntax:

 DC_IsStru ( <aStructure> ) -> lStatus

Returns:

 A logical .TRUE. if the file structure matches the array
 structure, .FALSE. otherwise.

Arguments:

<aStructure> is a multi-dimensional array with one sub-array
for each database field.

Element  Type   Description
------   ----   ------------------------
  [1]     C     Field Name
  [2]     C     Field Type
  [3]     N     Field Length
  [4]     N     Field Decimals
  [5]    Any    Default Data (optional)

Notes:

If DC_DBFILE() is used to open a database, the structure of the database will be automatically compared to the structure in the field dictionary and prompt the user to either update the structure of the database from the structure in the dictionary or update the dictionary to match the database.

Examples:

 aStru := { ;
   { 'CUST_NAME','C',25,0 },;
   { 'CUST_NMBR','C',10,0 },;
   { 'LAST_DATE','D',8,0  } }

 use customer
 if .not. DC_ISTRU( aStru )
   dc_struupdate( aStru )
 endif

Files:

_DCSTRU.PRG, DCLIP2.DLL

See Also:

   dc_struupdate()
   dc_modstru()
   dc_dbfile()


dc_isunique()

Is the current index a Unique index?

DC_ISUNIQUE() is used to report if the currently selected index is indexed UNIQUE (i.e. No duplicate keys in index ).<br><br>

Syntax:

 DC_IsUnique ( [<nArea>] ) -> lStatus

Returns:

 A logical .TRUE. if the index is Unique, .FALSE. otherwise.

Arguments:

<nArea> is the work area.  If no argument is passed then the
current work area will be reported.

Examples:

 use customer
 index on cust_name to custname
 ? DC_ISUNIQUE()
 .F.
 index on cust_name to custname unique
 ? DC_ISUNIQUE()
 .T.

Files:

_DCAREA.PRG, DCLIP1.DLL

See Also:

   dc_isdescend()


dc_jazzagekey()

A Get-Set function for posting the JazzAge Key

DC_JazzAgeKey() is a Get-Set function which is used to store the developer's individual JazzAge key that was received when JazzAge was registered.

Syntax:

DC_JazzAgeKey( [<cKey>] ) -> cOldKey

Returns:

A character string.

Arguments:

<cKey> is the JazzAge key that was received when registering
your copy of JazzAge.

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_printpreviewacrobat()


dc_jpgsize()

Returns the size of a JPEG file

DC_JPGSize() will return the size of a JPG file. It is much faster than using the XbpBitMap() class to determine the size.

Syntax:

DC_JPGSize( <cImage>, ;
            <@nWidth>, ;
            <@nHeight>) -> cStatus

Returns:

A Character string containing the status of whether or not the
size could be determined.

Arguments:

<cImage> is the full name, including path, of the JPEG file.

<@nWidth> is a variable, passed by reference, to store the width.

<@nHeight> is a variable, passed by reference. to store the height.

Files:

_DCFUNCT.PRG, DCLIPX.DLL


dc_keycount()

Return the number of "active" records

DC_KEYCOUNT() is used to calculate the number of "active" records in a database. This is accomplished by using a special agorithm that skips through the index in a manner must faster than simply skipping one record at a time and counting records. In many cases, this calculation can be accomplished in a fraction of a second, however, conditions can exist that may require a several seconds.

Syntax:

DC_KeyCount ( [<xTop>], ;
              [<xBottom>], ;
              [<nTimeOut>] ) -> nKeyCount

Returns:

 1. If there is no controlling index and no filter set then
    the total number of records in the database will be
    returned.

 2. If there is a controlling index and it is not a conditional
    index then the total number of records in the database will
    be returned.

 3. If there is a controlling index and it is also a
    conditional index then the number of keys in the index will
    be returned.

 4. If values are passed for xTop and/or xBottom and there is a
    controlling index, then the number of records between the
    xTop and xBottom values will be returned.

 5. -1 if DC_KeyStat() is set to .FALSE.

Arguments:

<xTop> is a value that matches the same type as the index
key to set as the top of the database.

<xBottom> is a value that matches the same type as the
index key to set as the bottom of the database.

<nTimeOut> is the amount of time (in seconds) to allow
DC_KEYCOUNT() to calculate the number of records.  If the
database is too large or the computer is too slow, this
calculation may take too much time to be practical.  If the
calculation takes longer than <nTimeOut> then -1 will be
returned.

Notes:

DC_KEYCOUNT() takes into consideration the scoping condition that was set with DC_SetScope() and counts only the number of records that fall into scope.

Examples:

 #include 'dcdialog.ch'
 #include 'appevent.ch'

 PROCEDURE XTest()

 LOCAL GetList := {}, oBrowse, aPres, cScopeTop, cScopeBot

 USE ..\XDOC\EXPRESS INDEX ..\XDOC\EXPRESS.CDX ;
    VIA FOXCDX ALIAS XDOC

 OrdSetFocus('COMMAND')
 DC_KeyStat(.t.)

 aPres := ;
  { { XBP_PP_COL_HA_FGCLR, GRA_CLR_WHITE },    /*  Header FG Color  */ ;
    { XBP_PP_COL_HA_BGCLR, GRA_CLR_DARKGRAY }, /*  Header BG Color  */ ;
    { XBP_PP_COL_DA_ROWSEPARATOR, XBPCOL_SEP_DOTTED }, /* Row Sep  */  ;
    { XBP_PP_COL_DA_COLSEPARATOR, XBPCOL_SEP_DOTTED }  /* Col Sep  */  ;
  }

 @ 3,1 DCBROWSE oBrowse ALIAS 'XDOC' ;
   SIZE 77,11.8 ;
   FREEZELEFT {1} ;
   PRESENTATION aPres

 DCBROWSECOL FIELD XDOC->command ;
   HEADER "Command" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->type  ;
   HEADER "Type" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->short ;
   HEADER "Short Description" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->module ;
   HEADER "Module" PARENT oBrowse ;

 DCBROWSECOL FIELD XDOC->category ;
   HEADER "Category" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->see_also ;
   HEADER "See Also" PARENT oBrowse

 DCREAD GUI ;
   FIT ;
   ADDBUTTONS ;
   TITLE 'Browse Scoping Demo' ;
   EVAL {||_SetNavBlocks(oBrowse),;
           DC_SetScope(0,'DC_G'),;
           DC_SetScope(1,'DC_K'),;
           DC_DbGoTop(),;
           oBrowse:RefreshAll() }

 RETURN

 /* -------------------- */

 STATIC PROCEDURE _SetNavBlocks( oBrowse )

 oBrowse:skipBlock     := {|n| DC_DbSkip(n)    }
 oBrowse:goTopBlock    := {| | DC_DbGoTop()    }
 oBrowse:goBottomBlock := {| | DC_DbGoBottom() }
 oBrowse:phyPosBlock   := {| | Recno()         }
 oBrowse:posBlock      := {| | DC_KeyNo()      }
 oBrowse:lastPosBlock  := {| | DC_KEYCOUNT()   }
 oBrowse:firstPosBlock := {| | 1               }

 RETURN

Files:

_DCSCOPE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_keyno()
   dc_setscope()
   dc_keystat()


dc_keyno()

Return the ordinal position of the current record

DC_KEYNO() is used to calculate the ordinal position of the current record in a "scoped" database. This is accomplished by using a special agorithm that skips through the index in a manner must faster than simply skipping one record at a time and counting records. In many cases, this calculation can be accomplished in a fraction of a second, however, conditions can exist that may require a several seconds.

Syntax:

DC_KeyNo ( [<nTimeOut>], ;
           [@<nKeyCount>] ) -> nKeyNo

Returns:

 1. If there is no controlling index and no filter set then
    the current record number (RECNO()) will be returned.

 2. If there is a controlling index then the ordinal position
    of the current record within the index will be returned.

 3. -1 if DC_KeyStat() is set to .FALSE.

Arguments:

<nTimeOut> is the amount of time (in seconds) to allow
DC_KEYNO() to calculate the number of records.  If the
database is too large or the computer is too slow, this
calculation may take too much time to be practical.  If the
calculation takes longer than <nTimeOut> then -1 will be
returned.

@<nKeyCount> is the name of a memory variable to save the
number of active records.  This count is the same as
returned by DC_KEYCOUNT().

Notes:

DC_KEYNO() is required to determine the ordinal position when using SCOPEs via DC_SetScope(), otherwise the Xbase++ function OrdKeyNo() provides this information.

Examples:

 #include 'dcdialog.ch'
 #include 'appevent.ch'

 PROCEDURE XTest()

 LOCAL GetList := {}, oBrowse, aPres, cScopeTop, cScopeBot

 USE ..\XDOC\EXPRESS INDEX ..\XDOC\EXPRESS.CDX ;
    VIA FOXCDX ALIAS XDOC

 OrdSetFocus('COMMAND')
 DC_KeyStat(.t.)

 aPres := ;
  { { XBP_PP_COL_HA_FGCLR, GRA_CLR_WHITE },    /*  Header FG Color  */ ;
    { XBP_PP_COL_HA_BGCLR, GRA_CLR_DARKGRAY }, /*  Header BG Color  */ ;
    { XBP_PP_COL_DA_ROWSEPARATOR, XBPCOL_SEP_DOTTED }, /* Row Sep  */  ;
    { XBP_PP_COL_DA_COLSEPARATOR, XBPCOL_SEP_DOTTED }  /* Col Sep  */  ;
  }

 @ 3,1 DCBROWSE oBrowse ALIAS 'XDOC' ;
   SIZE 77,11.8 ;
   FREEZELEFT {1} ;
   PRESENTATION aPres

 DCBROWSECOL FIELD XDOC->command ;
   HEADER "Command" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->type  ;
   HEADER "Type" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->short ;
   HEADER "Short Description" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->module ;
   HEADER "Module" PARENT oBrowse ;

 DCBROWSECOL FIELD XDOC->category ;
   HEADER "Category" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->see_also ;
   HEADER "See Also" PARENT oBrowse

 DCREAD GUI ;
   FIT ;
   ADDBUTTONS ;
   TITLE 'Browse Scoping Demo' ;
   EVAL {||_SetNavBlocks(oBrowse),;
           DC_SetScope(0,'DC_G'),;
           DC_SetScope(1,'DC_K'),;
           DC_DbGoTop(),;
           oBrowse:RefreshAll() }

 RETURN

 /* -------------------- */

 STATIC PROCEDURE _SetNavBlocks( oBrowse )

 oBrowse:skipBlock     := {|n| DC_DbSkip(n)    }
 oBrowse:goTopBlock    := {| | DC_DbGoTop()    }
 oBrowse:goBottomBlock := {| | DC_DbGoBottom() }
 oBrowse:phyPosBlock   := {| | Recno()         }
 oBrowse:posBlock      := {| | DC_KEYNO()      }
 oBrowse:lastPosBlock  := {| | DC_KeyCount()   }
 oBrowse:firstPosBlock := {| | 1               }

 RETURN

Files:

_DCSCOPE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_keycount()
   dc_keyno()
   dc_keystat()
   dc_setscope()


dc_keystat()

Enable or disable scoping

DC_KeyStat() is used to enable or disable the DC_KeyNo() and DC_KeyCount() functions. DC_KeyNo() and DC_KeyCount() can take a very long time to calculate the current record position or number of scoped records on very large databases. DC_KeyStat() can be used to turn off all scoping.<br><br>

Syntax:

DC_KeyStat ( [<lStat>] ) -> lStat

Arguments:

<lStat> if TRUE will enable DC_KeyNo() and DC_KeyCount().  If
<lStat> is FALSE the functions will be disabled.

Files:

_DCSCOPE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_keycount()
   dc_keyno()


DC_KeyString2Num()

Translate a key string to a numeric value

DC_KeyString2Num() s is used to translate a string that defines a key to a numeric Xbase++ equivalent. This is handy for data-driven applications.<br><br><br><br>

Syntax:

DC_KeyString2Num( <cKey> ) -> nKey

Returns:

A numeric value.

Arguments:

<cKey> is the name of the key.

Examples:

DC_KeyString2Num('Shift-F10') -> xbeK_SH_F10
DC_KeyString2Num('Ctrl-F10') -> xbeK_CTRL_F10
DC_KeyString2Num('Control-F10') -> xbeK_CTRL_F10

Files:

_DCPUTK.PRG, DCLIPX.DLL


dc_keytran()

Translate AppEvent() keyboard value to Inkey() value

DC_KEYTRAN() is used to translate an AppEvent() keyboard value to an Inkey() keyboard value or vice-versa.

Syntax:

DC_KeyTran ( <nKey>, ;
             [<nMode>] ) -> nKeyVal

Returns:

 A numeric value.

Arguments:

<nKey> is the AppEvent() value of the key to translate to
Inkey() if <nMode> is 1 (default).  If <nMode> is 2 then <nKey>
is the Inkey() value of the key to translate to AppEvent().

Examples:

 ? DC_KEYTRAN( xbeP_UP, 1 )
 5

 ? DC_KEYTRAN( K_UP, 2 )
 65574

Files:

_DCPUTK.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_appkeydefine()
   dc_appeventdefine()


dc_langblock()

Post a code-block for language translator

DC_LANGBLOCK() is used to post a code-block at the beginning of a program pointing to the function which performs translation of screen messages. It is used in conjunction with DC_LANGMSG(). <br><br>A default message and a numeric message ID are passed as parameters to the code block by DC_LANGMSG(). This code block points to a function which must return a message based on the message ID received. The function can be used to store messages in .DBF files,.INI files, in source code, or any other storage medium.<br><br>Messages in eXPress++ functions like DC_ReadGui() and the DC_Printer() class are translated via DC_LANGMSG() and numeric constants defined in DCMSG.CH. Normally, a language is selected via DC_LANGSET(), however, this function may be overridden by posting a custom language translator via DC_LANGBLOCK() thereby disabling the current language translator.<br><br>

Syntax:

DC_LangBlock( [<bCodeBlock>] ) -> bOldBlock

Returns:

A code block containing the previous translation block.  If no
code block has been posted, then a NIL is return.

Arguments:

<bCodeBlock> is a code block in the following form:

{ | cMessage, cID | MyTranslator( cMessage, cID ) }

Examples:

FUNCTION main

DC_LANGBLOCK( { |cMessage,cID| MyTranslator(cMessage,cID) } )

? DC_LangMsg( MYMSG_TESTING )
This is a test

? DC_LangMsg( DCMSG_HELP )
Helfen

? DC_LangMsg( DCMSG_CANCEL )
Absagen

RETURN

/* --------------------- */

FUNCTION MyTranslator( nMessage )

LOCAL nSaveArea := Select()

IF Select('GERMAN') = 0
  USE German
ENDIF

SEEK nMessage

IF !Eof()
  cMessage := GERMAN->message
ENDIF

SELE (nSaveArea)

RETURN cMessage

Files:

_DCLANG.PRG, DCLIPX.LIB

See Also:

   dc_langmsg


dc_langmsg()

Translate a message by language

DC_LANGMSG() is used as a "wrapper" function to translate messages based on language. It is used in conjunction with DC_LANGSET() for selecting a built-in language translation or with DC_LANGBLOCK() for selecting a custom language translation. A numeric message ID is passed to DC_LANGMSG(). Message ID's are constants which are defined in DCMSG.CH for standard eXPress++ messages used in dialog boxes, message boxes, print routines, etc. Only messages which are intended for the end user of an eXPress++ program are assigned numeric constants and are translated. All messages which are intended for the programmer (ie error messages) are displayed in English.<br><br>

Syntax:

DC_LangMsg( <nMessageID> ) -> cMessage

Returns:

A character string.

Arguments:

<nMessageID> is a numeric constant defined in DCMSG.CH.

<nMessageId> may be any additional numeric value defined by
the programmer when using a custom translator posted by
DC_LANGBLOCK().

Examples:

FUNCTION main

DC_LangSet('GERMAN')

? DC_LangMsg( DCMSG_HELP )
Helfen

? DC_LangMsg( DCMSG_CANCEL )
Absagen

RETURN

Files:

_DCLANG.PRG, DCLIPX.LIB

See Also:

   dc_langblock()


dc_langset()

Set the default language for eXPress++ messages

DC_LANGSET() is used to set the language for translating eXPress++ message. DC_LANGSET() is used in conjunction with DC_LANGMSG() for displaying messages on buttons, windows, etc. A numeric message ID is passed to DC_LANGMSG(). Message ID's are constants which are defined in DCMSG.CH for standard eXPress++ messages used in dialog boxes, message boxes, print routines, etc. Only messages which are intended for the end user of an eXPress++ program are assigned numeric constants and are translated. All messages which are intended for the programmer (ie error messages) are displayed in English.<br><br>

Syntax:

DC_LangMsg( [<nLanguage>] ) -> nOldLanguage

Returns:

A character string.

Arguments:

<nLanguage> is a numeric constant with a DCLANG_* prefix.  These
constants are defined in DCMSG.CH.

DCLANG_ENGLISH            - English
DCLANG_GERMAN             - German
DCLANG_PORTUGUESE         - Portuguese
DCLANG_SPANISH            - Spanish
DCLANG_CHINESE            - Chinese
DCLANG_FRENCH             - French
DCLANG_ITALIAN            - Italian
DCLANG_DUTCH              - Dutch
DCLANG_SLOVENIAN          - Slovenian
DCLANG_PORTUGUESE_BR      - Portuguese, Brazilian
DCLANG_SWEDISH            - Swedish
DCLANG_NORWEGIAN          - Norwegian
DCLANG_RUSSIAN            - Russian
DCLANG_POLISH             - Polish
DCLANG_SLOVAK             - Slovak
DCLANG_CZECH              - Czech
DCLANG_ROMANIAN           - Romanian
DCLANG_SIMPLIFIEDCHINESE  - Simplified Chinese
DCLANG_CROATIAN           - Croatian
DCLANG_HUNGARIAN          - Hungarian
DCLANG_TURKISH            - Turkish

Examples:

FUNCTION main

DC_LangSet(DCLANG_GERMAN)

? DC_LangMsg( DCMSG_HELP )
Helfen

? DC_LangMsg( DCMSG_CANCEL )
Absagen

RETURN

Files:

_DCLANG.PRG, DCLIPX.LIB

See Also:

   dc_langblock()
   dc_langmsg()


dc_lastfocus()

Store oXbp pointer for returning focus

DC_LastFocus() is used to store a pointer to oXbp object for returning focus after calling another window. DC_ReadGuiEventLoop() automatically returns focus to the last object that had focus when the objects main window receives focus. This can be overridden with DC_LastFocus().

Syntax:

DC_LastFocus( <aGetList>, ;
              [<oXbp>] ) -> oOldLastFocus

Returns:

Nil.

Arguments:

<aGetList> is a pointer to the GetList array.

<oXbp> is a pointer to the object.

Examples:

#include "dcdialog.ch"

function main()

local GetList[0], oMenuBar, oSubMenu, oDlg

dcmenubar oMenuBar

dcsubmenu oSubMenu prompt 'Test' ;
      action {|o|o:=Thread():new(),o:start({||Test(oDlg)})} ;
      parent oMenuBar

dc_readguidebug(2)
dcread gui parent @oDlg

return nil

* ------------

static function test( oDlg )

local getlist[0], d1 := date(), d2 := Date(), d3 := Date(), o1, o2, o3

@ 1,1 dcget d1 popup {|d|dc_popdate(d)} object o1
@ 2,1 dcget d2 popup {|d|dc_popdate(d)} object o2
@ 3,1 dcget d3 popup {|d|dc_popdate(d)} object o3

@ 5,1 dcpushbutton caption 'More Test' size 15,1.2 ;
      action {||msgbox('test'),DC_LASTFOCUS(GetList, o1)}

dcread gui fit addbuttons title 'Testing' appwindow oDlg:drawingArea

return nil

Files:

_DCGETBX.PRG, DCLIPX.DLL

See Also:

   dc_readguieventloop()


dc_lockmaint()

Maintain the "Lock" definition database

DC_LOCKMAINT() is used to maintain a database of "Locks" which are put onto files, menu items, or fields when designing an application. This database, DCLOCKS.DBF, is used as a reference only and is not needed to establish locks on menu items or other locks. The database simply provides a handy picklist to choose a lock to put on an item. The database assigns names and codes to locks.

Syntax:

DC_LockMaint ( [<lPickList>] ) -> cLockCode

Returns:

 A character string of three (5) characters representing the
 "lock" selected from the pick-list.

Arguments:

<lPickList> if .TRUE. will return the lock number from the
selected record when the <ENTER> key is pressed.  If .FALSE.,
(default) then the <ENTER> key will be used to edit the
current record.

Files:

_DCUSER.PRG

See Also:

   dc_usermaint()


dc_log()

Write system status to a log file

DC_LOG() will log information about the currently running procedure to a log file including the current status of work areas and environment variables.<br><br> A dialog window will be displayed first for the user to type in specific information that will be saved in the log file or to specify the name and location of the log file.

Syntax:

DC_Log ( [<cProcName>], ;
         [<nLineNmbr>], ;
         [<cInfo>], ;
         [<cFileName>], ;
         [<lOverWrite>], ;
         [<nLastKey>], ;
         [<cCurrScreen>] ) -> Nil

Returns:

 Nil

Arguments:

<cProcName> is the current procedure name.

<nLineNmbr> is the current line number.

<cInfo> is an information string.

<cFileName> is the name of the file to write.

<lOverWrite> if .TRUE. will overwrite <cFileName>, if .FALSE.
will append the information.

<nLastKey> is the last key hit value to include in the logged
data. If no argument is given then LASTKEY() is default.

<cCurrScreen> is the Screen contents you want to include in the
logged data.  If no argument is given then the current screen
contents is default.

Examples:

 FUNCTION error ( cMessage )

 save screen to cCurrScreen
 cProc := procname(1)  // proc name of calling procedure
 nLine := procline(1)  // line number of calling procedure

 DC_LOG( cProc, nLine, cMessage, "MYERR.LOG", .F., LASTKEY(),;
         cCurrScreen )

 RETURN .t.

Files:

_DCLOG.PRG, DCLIP2.DLL

See Also:

   LOG
   dc_setdclip()


dc_memoedit

A dual-mode replacement for MemoEdit()

DC_MemoEdit() is a dual-mode replacement for MemoEdit(). If the GUI flag has been turned on via the DC_Gui() function, then the parameters are passed on to DC_GuiMemoEdit() otherwise they are passed on to MemoEdit().

Syntax:

DC_MemoEdit( <cMemo>, ;
             <nTop>, ;
             <nLeft>, ;
             <nBottom>, ;
             <nRight>, ;
             <lEditMode>, ;
             <bcUserFunc>, ;
             <nLineLen>, ;
             <nTabSize>, ;
             <nBufferRow>, ;
             <nBufferCol>, ;
             <nWindowRow>, ;
             <nWindowCol>, ;
             <cTitle> ) -> cMemo

Files:

_DCMEMOE.PRG, DCLIPX.DLL

See Also:

   dc_guimemoedit()


dc_menu_p()

A nested, moused pull-down menu-system

DC_MENU_P() is a menu-system that creates pull-down, pop-up, or AT..PROMPT style menus with optional "high-lighted" characters, separator lines, "grayed (non-selectable)" items, message lines, and optional code-block evaluation.<br><br> DC_MENU_P() automatically supports both keyboard and mouse input. If the menu is a pop-up or pull-down menu, then clicking the mouse outside the menu prompt area is equivalent to pressing the escape key. The left button of the mouse is used to select the menu item. Press the ENTER key, the right mouse button, or double-click the left mouse button to invoke the selected item.<br><br> Menus may be "nested" to provide sub-menus and sub-sub-menus.<br><br> If a sub-array of Help-Messages is passed, then a more descriptive message about the prompt can be displayed (based on options) in a fixed window area on the screen or in a window that connects to the bottom of the pull-down menu. If a sub-array of Help-Codes is passed, then a context- specific help screen in the DCHELP.DBF database will displayed when the F1 key is pressed or the mouse is clicked in the help-message area.<br><br>

Syntax:

DC_Menu_P ( <nRow>, ;
            <nCol>, ;
            [<cTitle>], ;
            [<cColor>], ;
            [<cType>], ;
            [<lBar>], ;
            [<lRetVal>], ;
            [@<nStart>], ;
            <aPrompt>, ;
            [<aBlock>], ;
            [<aCoord>], ;
            [<aMsg>], ;
            [<aMsgOpt>], ;
            [<cExit>], ;
            [<lRestScrn>], ;
            [<lShadow>], ;
            [<aMouse>], ;
            [<lSticky>], ;
            [<aHelp>] ) -> cCode

Returns:

 If <lReturnVal> is .FALSE. (default) the hot-key character of the
 selected menu item will be returned.  If <lReturnVal> is .TRUE.,
 the CHR() value of the menu choice will be returned.   For example,
 if the 4th menu item is selected, then CHR(4) will be returned.

 A null string is returned if the ESCape key is pressed.

Arguments:

<nRow> is the upper-left row (for pull-downs), or lower-left
row (for pop-up menus).

<nCol> is the upper-left column (for pull-downs), or lower-left
column for pop-up menus).

<cTitle> is an Optional title to be displayed centered on the
top or bottom line of the box (depending on if it's a pull-down
or a pop-up box.)  If no title is desired use a null string
("").

<cColor> is a single string of 5 colors (separated by
commas) to be used for the frame, menu items, hi-lited letters,
select bar, grayed items respectively.  If no argument is
passed, then the dCLIP default colors will be used.

<cType> is a single character defining the type of menu:

   A - Pull-down menu
   B - Pop-up menu
   C - Plain menu, no borders (default)

<lBar>  if .TRUE. (default) will make the menu resemble a
MENU TO, with a select bar.  If you do not want a select bar,
and just want the items to be chosen by pressing the hot-key
letter only, set this to .FALSE.

<lRetVal> if .FALSE. (default) will return the hot-key
character of the selected menu item.  If .TRUE., the CHR()
value of the menu choice will be returned.   For example, if
the 4th menu item is selected, then CHR(4) will be returned.
This parameter should also be set to .TRUE. if you are
passing code-blocks to be evaluated and want to return from
the menu after evaluating the code-block.

<nStart> is a numeric or character value to determine which
element to start on.  If the type is numeric, then the starting
element is the number, if the type is character then the
starting element is the first item whose highlighted character
matches the <nStart> character.  The number of the menu item
selected will be stored in the value referenced by @<nStart>.

<aPrompt> is an array of menu prompts to be displayed.  The
first letter of each menu item will be hilited and will be
designated as that menu item's "hot-key".  If a different
hot-key letter is desired for a item, precede the desired
hot-key letter with a tilde (~).   If the item is a
"gray-scale" item (i.e. it displays only but is not
selectable), it must be preceded by an "*" character.  If the
item is a separator line, it must be passed as an "@"
character.  If the item is a separator line with a sub-title,
then it must be passed as a "@" character plus the sub-title
string. "Nesting" of sub-menus is accomplished by passing an
array of sub-menu information rather than a character string.
<aPrompt> may contain any mixture of character strings
(single items) or arrays (nested items).  Selection of a
nested item will pop-up a sub-menu.  To create nested items
pass an array with the following structure:

 Element  Type   Description
 -------  ----   ---------------------------------
   [1]   C     Menu prompt
   [2]   A     Array of sub-menu items
   [3]   A     Array of sub-menu code-blocks (optional)
   [4]     A     Array of sub-menu messages (optional)
   [5]     A     Array of sub-menu help-codes (optional)

<aBlock> is an optional array of code blocks.  Must be one
code block for each item in <aPrompt>.  If a code block array
is passed then the code block will be evaluated when the item
is selected and the user presses enter.

<aCoord> is an optional ragged array of Row/Column positions
for each item in <aPrompts>.  If a Row/Column array is not
passed then the prompts will be placed vertically starting at
<nRow> and <nCol>.

<aMsg> is an optional array of messages to be displayed for
each item in <aPrompt>.  Each item in this array is a
character string which will be displayed in a box or a single
line depending on the values in <aMsgOpt>.

<aMsgOpt> is an array of options on how to display the
message for the selected prompt.

Element Type  Description
------- ----- -----------------------------------------------
  [1]    N    Display Row if TYPE 0
  [2]    N    Display Column if TYPE 0 (-1 to center message)
  [3]    N    Message TYPE (0-Line, 1-Box, 2-Add to Pull-Down
  [4]    N    Start Row if TYPE 0,1 or Height if TYPE 2
  [5]    N    Start Column if TYPE 0,1 (-1 to center message)
              or Width if TYPE 2
  [6]    N    End Row if TYPE 1
  [7]    N    End Column if TYPE 1

<cExit> is a string containing the character value of any
keys that will exit the menu and return the pressed key value.
The ESCape key always exits.  If any "exit key" is pressed that
is not a menu item "hot key", then the key character value will
be returned.

<lRestScrn> if .TRUE. (default) will restore the previous
screen after exiting the menu.  If .FALSE. the menu and
highlighted selection will remain on the screen.

<lShadow> if .TRUE. (default only if <cType> is "A") will
display a shadow on the menu.

<aMouse> is a multi-dimensional array of mouse-buttons
to active outside the menu area.  See DC_MOUSEKEY() for
specifications.

<lSticky> is used to modify the behavior of DC_MENU_P() only
when a selected item has an associated code-block.  If
<lSticky> is true, the code-block will be evaluated while the
menu is still displayed on the screen. If .FALSE., then the
screen will be restored (only if <lRestoreScreen> is .TRUE.)
followed by the evaluation of the code-block.

<aHelp> is an optional array of Help-Codes for each prompt
item in <aPrompts>.  Each help-code is a character string
of up to 15 characters in length which matches the value in
the PROC_NAME field of the DCHELP.DBF database. The
concatenated values in the DCHELP.DBF memo fields will be
displayed in a memo window whenever the F1 key is pressed
after selecting a prompt.  See the function DC_HELPF1() for
more information on setting up context-specific help.

Notes:

The behavior of DC_MENU_P() depends on the current setting of the DC_WINMODE() function.

Examples:

 -- Example 1 --

 // This example demonstrates using DC_MENU_P() to return a
 // code letter based on a user menu selection

 local aPrompts, cMenuCode

 aPrompts :=  { 'Open File',;
                'Close File',;
                'Edit File',;
                'Save File',;
                'View File',;
                'Print File',;
                'Run Program',;
                'DOS ~Shell'  }

 cMenuCode := ;
   DC_MENU_P( 24, 28, ' File Options ', ;
     'bg+/rb,n/bg,w+/bg,w+/r,n+/bg', 'B', .t., .f., 'O', ;
     aPrompts )

 do case
   case cMenuCode = 'O'
     openfile()
   case cMenuCode = 'C'
     closefile()
   case cMenuCode = 'E'
     editfile()
   case cMenuCode = 'S'
     savefile()
   case cMenuCode = 'S'
     viewfile()
   case cMenuCode = 'P'
     printfile()
   case cMenuCode = 'R'
     runexe()
   case cMenuCode = 'S'
     rundos()
 endcase
 return

 -- Example 2 --

 // This example demonstrates using DC_MENU_P() to execute a
 // code block  based on a user menu selection

 local aPrompts, aBlocks

 aPrompts :=  { 'Open File',;
                'Close File',;
                'Edit File',;
                'Save File',;
                'View File',;
                'Print File',;
                'Run Program',;
                'DOS ~Shell'  }

 aBlocks := { {||openfile()},;
              {||closefile()},;
              {||editfile()},;
              {||savefile()},;
              {||viewfile()},;
              {||printfile()},;
              {||runexe()},;
              {||rundos()}     }

 DC_MENU_P( 24, 28, ' File Options ', ;
   'bg+/rb,n/bg,w+/bg,w+/r,n+/bg', 'B', .t., .f., 'O', ;
   aPrompts, aBlocks )

 return

 -- Example 3 --

 // This example shows how to "nest" sub-menus.
 // In the below example, selecting item 2 (File Options) of
 // the main menu will pop-up a sub-menu.  Selecting Item 1
 // (Delete a File) will pop-up another sub-menu.  Selecting
 // Item 2 (Binary File) will return "FDB".

 LOCAL aSubPrompt, aSubBlock, aMainPrompt, aSubSubPrompt

 aSubSubPrompt := {'ASCII File','Binary File','EXE File'}

 aSubPrompt := { ;
     {'Delete a file',aDelPrompt},;
      'Copy a file', ;
      'Move a file' }

 aSubBlock  := { , {||copyafile()}, {||moveafile()} }

 aMainPrompt := { ;
    'Edit Options',;
   {'File Options', aSubPrompt, aSubBlock },;
    'Search Options',;
    'Print Options' }

 cSelection := ;
  DC_Menu_P ( 10, 10, , , 'B', , , , aPrompt, , , , , , , , ,  )

Files:

_DCMENU2.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_menupull()
   dc_menumain()


dc_menu_to()

A moused replacement for MENU TO (__menuto())

DC_MENU_TO() is used with DC_AT_PROMPT() as a replacement for Clipper AT..PROMPT and MENU TO commands. DC_MENU_TO() will enable the dCLIP mouse system and allow menu selections by mouse or keyboard.<br><br> No other changes are required to source code to add the mouse to menus other than changing AT..PROMPT commands to DC_AT_PROMPT() and MENU TO commands to DC_MENU_TO() or #include "DCMOUSE.CH".

Syntax:

DC_Menu_To( [<nChoice>], ;
            [<nMsgRow>], ;
            [<nMsgCol>], ;
            [<cColor>] ) -> nChoice

Returns:

 The letter corresponding to the Hot-Key assigned to the menu item
 that was selected, a < sign if the left arrow was pressed, a > if
 the right arrow was pressed, or a null string if an error occured.

Arguments:

<nChoice> is the initial prompt to be highlighted.

<nMsgRow> is the optional screen row to display messages when a
prompt is selected.  If no argument is passed, then the row
established by the SET MESSAGE environment variable will be
used.

<nMsgCol> is the optional screen column to display messages
when a prompt is selected.  If no argument is passed, then the
message will be displayed at column 0 unless the SET MESSAGE
CENTER environment variable is active, then it will be centered
in the message row.  If -1 is passed the message will be
centered in the message row.

<cColor> is an optional color string of two colors separated
by commas.  The first color is the color of the unhighlighted
items and the second color is the color of the highlighted
item.  If no parameter is passed, then the current system color
setting will be used.

Examples:

 // display prompts
 dc_at_prompt( 10, 10, "Open a File", "Use a new database" )
 dc_at_prompt( 12, 10, "Open an Index", "Use an Index file" )
 dc_at_prompt( 14, 10, "Edit database", "Browse all records" )

 // get a user selection and display message at row 20, col 25
 nChoice := DC_MENU_TO( 1, 20, 25 )

Files:

_DCMENU2.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_menupull()


dc_menuaccel()

Process a menu Accelerator key

DC_MENUACCEL() is used to process an array of Accelerator key information. This array is created by DC_MENUCOMPILE() at the time that a Top-Bar/Pull-Down menu system is compiled into an array for later passing to DC_MENUMAIN(). In a standard loop where a key is pressed, this function is called to test whether or not the key pressed is an accelerator key. <br><br> (1) If it IS a valid key, then the data in the array is used to evaluate the code block and post a return value equal to the values in the menu array. After evaluating the code block and/or posting the return value, DC_MENUACCEL() will return a .TRUE. <br><br> (2) If it IS NOT a valid key, then DC_MENUACCEL() will return a .FALSE.<br><br>

Syntax:

DC_MenuAccel ( <aAccelKeys> ) -> lStatus

Returns:

 A logical value.

Arguments:

<aAccelKeys> is a multi-dimensional array of Accelerator
key data.  There is one sub-array for each accelerator key.
This sub-array has the following structure:

Element   Type   Description
-------  -----  ----------------------------------------
  [1]       N    Inkey() value of Accelerator key
  [2]       B    Code block to evaluate.  Pass as a NIL
                 if NONE.
  [3]       N    Numeric value to post as the value
                 returned by DC_MENURETURN() if the
                 accelerator key is hit.

Examples:

 local aMenus, aSubMenus, aMainMenu, aMouseKeys, nMenu,;
       aAccelKeys

 aMenus :=  { 'File','Edit','View','Run' }

 aSubMenus :=  { { 'Open File    <Alt-N>',;
                   'Close File   <Alt-C>',;
                   'e~Xit to Dos <Alt-X>' },;
                 { 'Edit File    <Alt-D>',;
                   'Save File    <Alt-S>' },;
                 { 'View File    <Alt-Z>',;
                   'Print File   <Alt-P>' },;
                 { 'Run Program  <Alt-O>',;
                   'DOS ~Shell   <Alt-L>'},;
                 nil,nil,nil,nil,;
               { 101, 102, 103, 104, 105, ;
                 106, 107, 108, 109 } }

 aAccelKeys := { { K_ALT_N,,101 },;
                 { K_ALT_C,,102 },;
                 { K_ALT_X,,103 },;
                 { K_ALT_D,,104 },;
                 { K_ALT_S,,105 },;
                 { K_ALT_Z,,106 },;
                 { K_ALT_P,,107 },;
                 { K_ALT_O,,108 },;
                 { K_ALT_L,,109 } }

 aMainMenu := { 1, 3, 'bg+/rb,n/bg,w+/bg,w+/r,n+/bg', 'BAD', ;
                .t., 'FO', { aMenus }, { aSubMenus }, 'X' }

 /* -- Paint the menu bar and get the mouse coordinates -- */
 DC_MENUMAIN( aMainMenu,.t.,@aMouseKeys )

 do while .t.

   nInkey := DC_Inkey(0)  /* -- Get  a key -- */
   cCode  := UPPER(CHR(nInkey))

   do case

     case nInkey = K_ESC
       exit

     /* -- mouse click -- */
     case nInkey <= -101  .AND. !Empty(DC_MouseKeys(aMouseKeys))

     /* -- Menu key was hit -- */
     case cCode $ 'FEVR' .OR. DC_MENUACCEL( aAccelKeys, nInkey )

       IF DC_MenuReturn() = 0  /* -- Not an Accelerator -- */
         DC_MENUMAIN( aMainMenu,,,cCode )
       ENDIF
       nMenu := DC_MenuReturn(0)

       do case

         case nMenu = 101
           openfile()
         case nMenu = 102
           closefile()
         case nMenu = 103
           __Quit()
         case nMenu = 104
           editfile()
         case nMenu = 105
           savefile()
         case nMenu = 106
           viewfile()
         case nMenu = 107
           printfile()
         case nMenu = 108
           runexe()
         case nMenu = 109
           rundos()

       endcase

    endcase

 enddo
 return

Files:

_DCMENU2.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_menumain()
   dc_menucompile()


dc_menuarray()

Create an array of mouse buttons for a single-line menu bar

DC_MENUARRAY() is used to make single line "moused" menus easier to create and maintain. This function will return an array of mouse buttons to later pass to DC_MOUSEKEY() and a menu string to pass to DC_DBCHOICE().

Syntax:

DC_MenuArray ( <nStartRow>, ;
               <nStartCol>, ;
               <nEndCol>, ;
               [<cNormColor>], ;
               [<cHiliteColor>], ;
               <aItems>, ;
               <lDisplay>, ;
               [@<cMenuBar>] ) -> aMouseButtons

Arguments:

<nStartRow> is the display row to paint the menu bar and
mouse buttons.

<nStartCol> is the start display column to paint the menu bar
and mouse buttons.

<nEndCol> is the end display column.

<cNormColor> is the normal color of the menu bar.

<cHiliteColor> is the highlight color of menu items hot key
letter for each item.

<aItems> is an array of menu items to display

<lDisplay> if .true. (default) will paint the menu bar on the
screen.  If .false., then the items menu bar will not be
displayed but the mouse-button array and menu string will still
be returned.

@<cMenuBar> is the name of the variable to store the string value
of the menu.

Examples:

 local aMenus, cMenuBar, aMouseKeys

 aMenus := { ;
    'File ',;
    'Edit ',;
    'View ',;
    'Search ',;
    'Print ',;
    'Maint }

  aMouseKeys := ;
     DC_MENUARRAY( 0, 0, 79, , , aMenus, .f., @cMenuBar )

Files:

_DCMENUB.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_menubar()
   dc_menumain()


dc_menubar()

Paint a menu bar with key characters highlighted

DC_MENUBAR() is used to paint a menu bar with highlighted "hot keys".

Syntax:

DC_MenuBar( <nRow>, ;
            <nCol>, ;
            <cColors>, ;
            <cBarText>, ;
            [<lHide>] ) -> cMenuBar

Returns:

 A character string which contains the screen contents of
 the menubar for later restoring the screen with RESTSCREEN().

Arguments:

<nRow> and <nCol> are the screen coordinates to display the
menu bar.

<cColors> is a Normal and Highlight color string, separated by
a comma.

<cBarText> is the text which is to appear in the menu.
Separate each menu item in Menu_String with a space.  By
default, the first letter of each word in <cBarText> will be in
the Highlight color unless another letter in that word is
preceded by a tilde (~). Any letter in a word preceded by a
tilde will be highlighted instead of the first letter.

<lHide> if .TRUE. will hide the menubar from being displayed
on the screen and will only return the screen contents.  If
.FALSE. (default), then the menu bar will be displayed.

Examples:

 DC_MENUBAR( 24, 0, "b/w,w+/w", " One Two T~hree Four F~ive " )

Files:

_DCMENUB.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_menuarray()
   dc_menumain()


dc_menucompile()

Compile a Menu Array

DC_MENUCOMPILE() is used to convert a menu array that was created by DC_MENUEDIT() or retrieved by DC_MENULOAD().<br><br> A menu that is stored as an array file or is retreived from the DCMENU.DBF menu-dictionary cannot contain code blocks, therefore they it must contain character-string equivalents of code-blocks. This type of menu-array is formatted in a way that provides for easy browsing and storage/retreival however, it is not formatted in a way that can be passed to the menu execution programs - DC_MENURUN(), DC_MENUMAIN(), DC_MENUPULL() or DC_MENUOSYS() therefore it must be converted or "compiled" into an array that can be used by these menu functions.<br><br> This function also supports conditional compiling based on sets of keys or code blocks.<br><br><br><br>

Syntax:

dc_menucompile ( <aPreMenu>, ;
                 [<cCompileKeys>],;
                 [<cAccessKeys>],;
                 [@<aAccelKeys>] ) -> aMenuRun

Returns:

 A multi-dimensional array containing all information about a
 menu including prompts, sub-menus, message-text,  help-codes,
 code-blocks, access codes, and return values.

 If the menu type is a Top-Bar Menu (Type A,B,C) or a TreeView
 menu then the array returned conforms to the specification for
 the array passed to DC_MENUMAIN(), DC_MENUOSYS() or
 DC_MENUTREE().

 If the menu type is a Pull-Down Menu (Type P) then the
 array returned conforms to the specification for the array
 passed to DC_MENUPULL().

Arguments:

<aPreMenu> is a menu array that conforms to the
specifications of the array returned by DC_MENUEDIT().

<cCompileKeys> is an optional list of keys (5-digit character
strings separated by commas).  Compile Keys are used for
conditional compiling of menu items.  Conditional compiling
allows for optionally excluding items from a menu in which the
COMPILE KEY does not match one of the keys in the list.
<cCompileKeys> supports wildcards.  This allows for designing
of menus that are similar but may have minor changes.  Conditional
compiling reduces redundancy and keeps the DCMENU.DBF dictionary
from growing too large.  See DC_MENUEDIT() for more information.
If this parameter is not used, then all menu items will be compiled
and included in the menu, otherwise, only the items in which
the COMPILE KEY EMPTY or matches one of the keys in the
list will be compiled.

<cAccessKeys> is an optional list of keys (5-digit character
strings separated by commas).  Access Keys are used for
conditional compiling of menu items based on a list of keys
assigned to a Logged-On user.  Conditional compiling allows for
optionally excluding items from a menu in which the ACCESS key
does not match one of the keys in the list.  <cAccessKeys> supports
wildcards.  This allows for designing of menus allow access to
menu items based on assigned user keys.   See DC_MENUEDIT() for
more information.  If this parameter is not used, then all menu
items will be compiled and included in the menu, otherwise, only
the items in which the ACCESS KEY is EMPTY or matches one of the
keys in the list will be compiled.

@<aAccelKeys> is a reference to store an array of Accelerator
key data.  Accelerator keys are hot-keys that perform the
same function as selecting the item from the menu, except
that the menu is not painted.  This array is passed to
DC_MENUACCEL() along with the value of the key that was hit.
See DC_MENUACCEL() for a specification of this array.

<aPreMenu> is a menu array that conforms to the
specifications of the array returned by DC_MENUEDIT().

<cCompileKeys> is an optional list of keys (5-digit character
strings separated by commas).  Compile Keys are used for
conditional compiling of menu items.  Conditional compiling
allows for optionally excluding items from a menu in which the
COMPILE KEY does not match one of the keys in the list.
<cCompileKeys> supports wildcards.  This allows for designing
of menus that are similar but may have minor changes.  Conditional
compiling reduces redundancy and keeps the DCMENU.DBF dictionary
from growing too large.  See DC_MENUEDIT() for more information.
If this parameter is not used, then all menu items will be compiled
and included in the menu, otherwise, only the items in which
the COMPILE KEY EMPTY or matches one of the keys in the
list will be compiled.

<cAccessKeys> is an optional list of keys (5-digit character
strings separated by commas).  Access Keys are used for
conditional compiling of menu items based on a list of keys
assigned to a Logged-On user.  Conditional compiling allows for
optionally excluding items from a menu in which the ACCESS key
does not match one of the keys in the list.  <cAccessKeys> supports
wildcards.  This allows for designing of menus allow access to
menu items based on assigned user keys.   See DC_MENUEDIT() for
more information.  If this parameter is not used, then all menu
items will be compiled and included in the menu, otherwise, only
the items in which the ACCESS KEY is EMPTY or matches one of the
keys in the list will be compiled.

@<aAccelKeys> is a reference to store an array of Accelerator
key data.  Accelerator keys are hot-keys that perform the
same function as selecting the item from the menu, except
that the menu is not painted.  This array is passed to
DC_MENUACCEL() along with the value of the key that was hit.
See DC_MENUACCEL() for a specification of this array.

Examples:

 /* --- Load menu from menu-dictionary --- */
 aPreMenu := DC_MenuLoad( 'MAINMENU' )

 /* --- Compile menu --- */
 aMenuMain := DC_MENUCOMPILE( aPreMenu )

 /* --- Run Menu --- */
 cMenuString := DC_MenuRun( aMenuMain )

 /* -- Compile menu and include Conditional Items -- */
 aMenuMain := DC_MENUCOMPILE( aPreMenu, 'A**,B2*', ;
                              DC_UserInfo(USER_KEYS) )

Files:

_DCMENUE.PRG

See Also:

   dc_menurun()
   dc_menuload()


dc_menuedit()

A Complex Pull-Down Menu Editor

DC_MENUEDIT() is a menu-designer system that will create complex pull-down menus. Menus are designed by entering information in a browse-style window that displays menu items and sub-menus in an easy-to-read "indented" format. The designed menu can be saved to an array, an array file, the data-dictionary, or to source-code which can be compiled and run by your application.<br><br> DC_MENUEDIT() creates menus that are passed as an array to the DC_MENUMAIN() (Text Mode Readero) or DC_MENUOSYS() (Gui Mode Reader) functions for execution. During the menu design process, the menu can be executed in a WYSIWIG fashion to provide instant feedback that the menu will function as it has been designed.<br><br> DC_MENUEDIT() supports all the features of DC_MENUMAIN() and DC_MENUOSYS() including sub-sub-menus, automatic mouse support, message boxes, help-codes, accelerator keys, code-blocks, and access keys. In addition, DC_MENUEDIT() supports conditional compiling of menu items to exclude key items at run-time based on a key list that is passed to DC_MENURUN() or DC_MENUCOMPILE() or based on a code block.<br><br>

Syntax:

 DC_MenuEdit( [<acMenu>], ;
              [<lCreate>] ) -> aMenu

Returns:

 A multi-dimensional array consisting of 2 sub-arrays.
 This array is formatted in such a way to ease the
 process of browsing, storage and retreival.  Since
 code-blocks cannot be saved and restored a character
 string equivalent is included in this array for compiling
 by the DC_MENUCOMPILE() function.

 Note : *T designates Text Mode Only
        *G designates Gui Mode Only

 Element [1] Contains all global information about the menu:

 Element  Type   Contents
 ------- ----   -------------------------------------
  [1]      C     Name of the menu - Up to 8 digits
  [2]      C     A description of this menu
  [3]      C     Type of menu - 4 characters
                 Char 1 : A - Bar Menu (standard)
                          B - Bar Menu (boxed) - *T
                          C - Bar Menu (underlined) - *T
                          P - PullDown Menu
                          T - Tree-Style Menu - *G
                 Char 2 : A - Size bar to Item Width - *T
                          B - Size bar to Screen Width - *T
                 Char 3 : U - Attached menus are Pull-Up - *T
                          D - Attached menus are Pull-Down - *T
                 Char 4 : M - MainLevel Heirarchy - *T
                          S - SubLevel Heirarchy - *T
  [4]      N     Spaces between items on top menu bar -*T
  [5]      C     A string of characters designating keys
                 which will exit the menu
  [6]      N     Start Top-Bar display row if Bar menu or - *T
                 start display row if Pull-Down menu
  [7]      N     Start Top-Bar display column if Bar menu or - *T
                 start display column if Pull-Down menu
  [8]      C     A string containing menu colors separated - *T
                 by commas.  See DC_MENUMAIN() for specs.
  [9]      L     .T. - Sticky Menus (menu will stay on screen - *T
                       when code-block evaluated.  Will return
                       to menu after evaluating code-block.
                 .F. - Normal Menus (screen will be restored - *T
                       before evaluating code-block.
 [10]      L     Re-Display menu after evaluating code-block - *T
 [11]      N     Message Display Option: - *T
                 0 - 1 line of the display
                 1 - A boxed area of the display
                 2 - A box under each pull-down
 [12]      N     Start Row (Message Display Option 1) or - *T
                 Box Height (Message Display Option 2) - *T
 [13]      N     Start Column (Message Display Option 1) or - *T
                 Box Width (Message Display Option 2)
 [14]      N     End Row (Message Display Option 1 only) - *T
 [15]      N     End Column (Message Display Option 2 only) - *T
 [16]      A     An optional array of Mouse Keys (see - *T
                 DC_MOUSEKEY() for specs.

 Element [2] contains all the items in the menu:
 Each Item in Element [2] is a sub-array of 12 elements:

 Element  Type   Contents
 -------  ----   ----------------------------------------
  [1]      C     Level - This is a character string that
                 establishes the heirarchal level of the
                 menu or sub-menu.
  [2]      C     The title of the menu item.  Enter a
                 tilde <~> or ampersand <&> character in
                 front of the hot-key character to be high-
                 lighted or underlined.
  [3]      C     A character-string representation of any
                 code-block to be compiled and evaluated.
                 The menu item will be "grayed" and
                 unselectable if the evaluated code block
                 returns a .FALSE.  The menu item will be
                 selectable if this element is left blank
                 or the evaluated code block returns a .TRUE.
  [4]      B     The code-block that has been compiled from
                 element 3.
  [5]      C     A character string containing the message
                 or long description to be displayed in the
                 message area of the selected menu item.
  [6]            <reserved>
  [7]      C     A character-string representation of any
                 code-block to be compiled and evaluated.
                 The code block will be evaluated when the
                 menu item is selected.  If this element is
                 left blank, then no code block will be
                 executed and the selected menu(s) will be
                 returned as a string.
  [8]      B     The code-block that has been compiled from
                 element 7.
  [9]      C     A string that is passed to the HELP procedure
                 as the fourth (4th) parameter when the F1
                 key is pressed.  This can be used as a help
                 code to pop-up additional help for this
                 menu item. - *T
  [10]     C     Access key for this menu.  Access key list
                 assigned to logged on user() must contain this
                 key or a wildcard to access this menu. If
                 element is left blank then menu item is
                 accessible by everyone.
  [11]     N     Return value to save to a static value when
                 this item is selected.  See DC_MenuReturn().
  [12]     C     Compile key for this menu.  Compile key list
                 passed to DC_MENUCOMPILE() must contain this
                 key or a wildcard to compile this item. If
                 element is left blank then the menu item will
                 be compiled regardless of the key list that is
                 passed.

Arguments:

<acMenu> is the name of the menu or the menu contents. If
<acMenu> is a character string, it is a name of up to eight (8)
digits.  If <acMenu> is an array, it must conform to the
specifications of a menu array defined in the RETURNS section.
If a menu name is passed then the DCMENU.DBF menu dictionary
database will be searched and all menu items that match the
menu name be loaded into an array for editing. If a NIL is
passed, then a pick-list of all menus stored in the DCMENU.DBF
database will be displayed.  If none is chosen, then it will
be assumed that you wish to create a new menu.

<lCreate> if .TRUE. will create a new menu.

Examples:

 /* -- Edit the Main Menu -- */
 aPreMenu := DC_MENUEDIT( 'MAINMENU' )

 /* -- Compile the menu -- */
 aMenuMain := DC_MenuCompile( aPreMenu )

 /* -- Install the menu -- */
 DC_MenuOSys( aMenuMain, oDialog )

Files:

_DCMENUE.PRG

See Also:

   dc_menurun()
   dc_menuload()


dc_menuload()

Load a menu from the Menu Dictionary

DC_MENULOAD() is used to retreive a menu from the Menu-dictionary database. Menus are stored in the DCMENU.DBF database via the DC_MENUEDIT() function or DC_MENUSAVE() function.<br><br><br><br><br><br>

Syntax:

DC_MenuLoad ( [<cMenuName>], ;
              [<cMode>], ;
              [<lCache>], ;
              [<cType>], ;
              [<cTitle>], ;
              [<lImport>] ) -> aMenu

Returns:

 A multi-dimensional array that conforms to the
 specification of the array returned by DC_MENUEDIT().

Arguments:

<aPreMenu> is a menu array that conforms to the specifications of the array returned by DC_MENUEDIT().

<cCompileKeys> is an optional list of keys (5-digit character
strings separated by commas).  Compile Keys are used for
conditional compiling of menu items.  Conditional compiling
allows for optionally excluding items from a menu in which the
COMPILE KEY does not match one of the keys in the list.
<cCompileKeys> supports wildcards.  This allows for designing
of menus that are similar but may have minor changes.  Conditional
compiling reduces redundancy and keeps the DCMENU.DBF dictionary
from growing too large.  See DC_MENUEDIT() for more information.
If this parameter is not used, then all menu items will be compiled
and included in the menu, otherwise, only the items in which
the COMPILE KEY EMPTY or matches one of the keys in the
list will be compiled.

<cAccessKeys> is an optional list of keys (5-digit character
strings separated by commas).  Access Keys are used for
conditional compiling of menu items based on a list of keys
assigned to a Logged-On user.  Conditional compiling allows for
optionally excluding items from a menu in which the ACCESS key
does not match one of the keys in the list.  <cAccessKeys> supports
wildcards.  This allows for designing of menus allow access to
menu items based on assigned user keys.   See DC_MENUEDIT() for
more information.  If this parameter is not used, then all menu
items will be compiled and included in the menu, otherwise, only
the items in which the ACCESS KEY is EMPTY or matches one of the
keys in the list will be compiled.

@<aAccelKeys> is a reference to store an array of Accelerator
key data.  Accelerator keys are hot-keys that perform the
same function as selecting the item from the menu, except
that the menu is not painted.  This array is passed to
DC_MENUACCEL() along with the value of the key that was hit.
See DC_MENUACCEL() for a specification of this array.

<aPreMenu> is a menu array that conforms to the
specifications of the array returned by DC_MENUEDIT().

<cCompileKeys> is an optional list of keys (5-digit character
strings separated by commas).  Compile Keys are used for
conditional compiling of menu items.  Conditional compiling
allows for optionally excluding items from a menu in which the
COMPILE KEY does not match one of the keys in the list.
<cCompileKeys> supports wildcards.  This allows for designing
of menus that are similar but may have minor changes.  Conditional
compiling reduces redundancy and keeps the DCMENU.DBF dictionary
from growing too large.  See DC_MENUEDIT() for more information.
If this parameter is not used, then all menu items will be compiled
and included in the menu, otherwise, only the items in which
the COMPILE KEY EMPTY or matches one of the keys in the
list will be compiled.

<cAccessKeys> is an optional list of keys (5-digit character
strings separated by commas).  Access Keys are used for
conditional compiling of menu items based on a list of keys
assigned to a Logged-On user.  Conditional compiling allows for
optionally excluding items from a menu in which the ACCESS key
does not match one of the keys in the list.  <cAccessKeys> supports
wildcards.  This allows for designing of menus allow access to
menu items based on assigned user keys.   See DC_MENUEDIT() for
more information.  If this parameter is not used, then all menu
items will be compiled and included in the menu, otherwise, only
the items in which the ACCESS KEY is EMPTY or matches one of the
keys in the list will be compiled.

@<aAccelKeys> is a reference to store an array of Accelerator
key data.  Accelerator keys are hot-keys that perform the
same function as selecting the item from the menu, except
that the menu is not painted.  This array is passed to
DC_MENUACCEL() along with the value of the key that was hit.
See DC_MENUACCEL() for a specification of this array.

<cMenuName> is the name of the menu.  This is a name of up to
eight (8) digits.  If a menu name is passed then the DCMENU.DBF
database will be searched and all menu items that match the
menu name be loaded into an array.  If no name is passed, then
a pick-list of all menus stored in the DCMENU.DBF database will
be displayed.

<cMode> is a single character designating the source:
  A - From an Array File.  If this option is chosen then
      the file named <cMenuName>.DCM will be used to load the
      array (if it exists).
  F - From a Function.  If this option is chosen then the
      function <cMenuName>_M() will be called to get the
      array (if it exists).
  D - From the DCMENU.DBF dictionary.  A Menu Configuration
      with the Tag Name <cMenuName> will be loaded into the
      array (if it exists).
  NONE - If no parameter is passed, then the array will be
  loaded first from the function <cMenuName>_M(), if it
  exists, and secondly from the file <cMenuName>.DCM if it
  exists, and thirdly from the DCMENU.DBF dictionary.

<lCache> if .TRUE. (default) will save the menu to a static
cache so the next time it is requested it will be reloaded
from the cache for faster speed.  If .FALSE. or if the
DC_MEMCACHE() setting is 0, then it will not be saved to the
static array.

<cType> is a character string designating the types of menus
to display in the pick-list of menus that will be displayed
(if no <cMenuName> is passed, or if the menu does not exist).
The default it all types (ABCPT).

<cTitle> is the title to display on the pick-list of menus
to display (if no <cMenuName> is passed, or if the menu does
not exist).  The default is "Pick a Menu to Load".

<lImport> if .TRUE. will attempt to load the menu from a
dictionary file named DXMENU.DBF rather than the standard
dictionary named DCMENU.DBF.

Notes:

The DCMENU.DBF file is the data-dictionary database that contains all menus. If this file does not exist in your default directory or path then it will be created.

A Menu may also be restored from an ARRAY file by using the DC_ARESTORE() function.

Example:

aMenu := DC_MenuLoad( "MAINMENU" ) DC_ASave( aMenu, "MAINMENU.DCM" ) aMenu := DC_ARestore( "MAINMENU.DCM" )

Examples:

 /* -- Load the Main Menu -- */
 aPreMenu := DC_MENULOAD( 'MAINMENU' )

 /* -- Compile the menu -- */
 aMenuMain := DC_MenuCompile( aPreMenu )

 /* -- Install the menu -- */
 DC_MenuOSys( aMenuMain, oDialog )

Files:

_DCMENUE.PRG

See Also:

   dc_menurun()
   dc_menuedit()


dc_menulock()

Lock all Menu items

DC_MENULOCK() modifies the behavior of the menu locking system. The default is .FALSE. In this "normal" mode, all menu items are accessible by all users if a menu item is not assigned a lock in the menu editor. If <lMode> is .TRUE., then NO menu item will be accessible unless it is assigned a lock or an asterisk (*) to make it accessible by everyone.

Syntax:

DC_MenuLock ( [<lMenuLock>] ) -> lMenuLock

Returns:

 A logical value containing the previous setting.

Arguments:

<lMenuLock> if .TRUE. will lock all menu items.  .FALSE. (default)
will unlock all menu items unless a lock has been placed on the
individual item.

Notes:

The DCMENU.DBF file is the data-dictionary database that contains all menus. If this file does not exist in your default directory or path then it will be created.

A Menu may also be restored from an ARRAY file by using the DC_ARESTORE() function.

Example:

aMenu := DC_MenuLoad( "MAINMENU" ) DC_ASave( aMenu, "MAINMENU.DCM" ) aMenu := DC_ARestore( "MAINMENU.DCM" )

Examples:

 /* -- Lock all Menus -- */
 DC_MENULOCK(.t.)

Files:

_DCMENU2.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_lockmaint()


dc_menumain()

An "integrated" menu system with a bar and pull-downs

DC_MENUMAIN() is an "integrated", moused menu-system that provides a set of pull-down or pop-up sub-menus from a main menu. <br><br> Pull-down menus may be "nested" to as many levels as desired to provide sub-menus and sub-sub-menus. A "main menu" is displayed with a set of prompts. When an item is selected from the main menu, the sub-menu will be displayed with it's set of prompts. Items in sub-menus may have sub-sub-menus. Each sub-sub-menu will be displayed to the immediate right of the sub-menu from which it was invoked. If there is no room on the right side of the screen the sub-sub-menu will be displayed on the left side.<br><br> The LEFT mouse button or keyboard arrow keys are used to navigate thru the menus. The ENTER key, RIGHT mouse button, or Double-Click of the left button are used to make the selection. If DC_INKEYWIN() is activated, then a menu item is selected when the left mouse button is released (similar to Windows).<br><br> If the mouse is clicked outside any active menu area the display will be restored and DC_MENUMAIN() will return a null "" string.<br><br> Sub-Arrays of Top-Bar Prompts, Sub-Menus, Code Blocks, Enabler-Blocks, Help-Messages and Help-Codes are included in the array that is passed to DC_MENUMAIN().<br><br> If a sub-array of Help-Messages is passed, then a more descriptive message about the prompt can be displayed (based on options) in a fixed window area on the screen or in a window that connects to the bottom of each pull-down menu. If a sub-array of Help-Codes is passed, then a context- specific help screen in the DCHELP.DBF database will displayed when the F1 key is pressed or the mouse is clicked in the help-message area.<br><br> If a sub-array of Return-Values is passed, then the value of the element associated with the selected menu item will be posted to a STATIC variable which can be read with the DC_MENURETURN() function.<br><br> If a FUNCTION KEY was pressed that was not previously set to call a code-block with SETKEY(), then pressing that function key will cause the value of the key (i.e. -10) to be saved to the static variable to be returned by DC_MENURETURN(). <br><br>

Syntax:

DC_MenuMain ( <aMenu>, ;
              [<lMenuBar>], ;
              [@<aMouseKeys>] ) -> cMenu

Returns:

 A character string with the "hot-key" value of the main menu
 and all sub-menus selected.  For example, if the "A" key was
 pressed to select an item in a sub-sub-menu that was selected
 from a sub-menu with the 'G' key that was selected from the
 top-bar menu with the "F" key, then "FGA" will be returned.

Arguments:

Parameters may be passed separately or in an array.  If
the first element is a Numeric value, then it is assumed
that all data will be passed as separate parameters and
the two optional parameters ( <lMenuBar> and <aMouseKeys> )
are not supported.  This is provided for compatability with
previous versions of dCLIP so existing applications will
run without requiring source-code modifications.  It is
recmmended that all parameters be passed in an array
<aMenu> with the following structure:

---------------------------------------------------------

Specification of <aMenu>:

Element  Type   Description (see below)
------- ----   -----------------------------------
  [1]     N     <nRow>
  [2]     N     <nCol>
  [3]     C     <cMenuColor>
  [4]     C     <cType>
  [5]     L     <lSelectBar>
  [6]     C     <cStart>
  [7]     A     <aMenus>
  [8]     A     <aSubMenus>
  [9]     C     <cExitKeys>
 [10]     L     <lReturnVal>
 [11]     N     <nSubMenu>
 [12]     N     <nSubSubMenu>
 [13]     A     <aMouseKeys>
 [14]     L     <lSticky>
 [15]     A     <aMsgOptions>
 [16]     L     <lReMenu>
 [17]     C     <cHeirArchy>

<nRow> is the start display row

<nCol> is the start display column

<cMenuColor> is a single string of 5 colors (separated by
commas) to be used for the frame, menu prompts, hi-lited
letters, select bar, and "grayed" items respectively.

<cType> is a 3-character string defining the type of menu bar:

   Char 1:  A - no box around menu bar (default)
            B - Single line box around menu bar
            C - Single line below menu bar
                Double line above menu bar

   Char 2:  A - Size box to size of menu items (default)
            B - Size box to full screen width

   Char 3:  D - Pull-down menus
            U - Pop-up menus

<lSelectBar> if .TRUE. (default) will make the menu resemble a
MENU TO, with a select bar.  If you do not want a select bar,
and just want the items to be chosen by pressing the hot-key
letter only, set this to .FALSE.

<cStart> is a 2-character string defining which menu item to
pre-select.  The first character is the "high-lighted"
character of the main menu.  The second character is the
"high-lighted" character of the sub-menu.

<aMenus) is a 2-dimensional array of top-bar menu prompts and
optional code blocks.  The first letter of each menu item will
be hilited and will be designated as that menu item's "hot-key".
If a different hot-key letter is desired for a item, precede
the desired hot-key letter with a tilde (~).   If the item is a
"gray-scale" item (i.e. it displays only but is not
selectable), it must be preceded by an "*" character. If the
secondary array of code blocks is passed there must be one code
block for each menu item in sub array 1.  If a code block array
is passed then the code block will be evaluated before
returning.

<aSubMenus> is an array of two sub-arrays. There must
be one sub-menu array for each <aMenu> prompt. The first
sub-array consists of up to 6 parallel arrays:

 [1] - Prompts
 [2] - Code-Blocks
 [3] - Messages
 [4] - Help Codes
 [5] - Access Codes
 [6] - Return Values

These arrays must conform to the specification for <aPrompts>
in DC_MENUPULL(). The second (parallel) sub-array is an optional
array of code-blocks which conforms to the specification for
code blocks <aBlocks> in DC_MENUPULL().  Nesting sub-sub-menus
from any one of the sub-menus is accomplished in the same
manner as described in the documentation for DC_MENUPULL().

<cExitKeys> is a string containing the character value of any
keys that will exit the menu and return the pressed key value.
The ESCape key always exits.  If any "exit key" is pressed that
is not a menu item "hot key", then the key character value will
be returned.

<lReturnVal> if .FALSE. (default) will return the hot-key
character of the selected menu item.  If .TRUE., the CHR()
value of the menu choice will be returned.   For example, if
the 4th menu item is selected, then CHR(4) will be returned.

<nSubMenu> is the number of Pull down menu to select as the
default.

<nSubSubMenu> is the number of the SubMenu to select as the
default>

<aMouseKeys> is a multi-dimensional array of mouse-buttons
to active outside the menu area.  See DC_MOUSEKEY() for
specifications.

<lSticky> is used to modify the behavior of DC_MENUMAIN() only
when a selected item has an associated code-block.  If
<lSticky> is true, the code-block will be evaluated while the
menu is still displayed on the screen. If .FALSE. (default),
then the screen will be restored followed by the evaluation of
the code-block.

<aMsgOptions> is an array of options on how to display the
message for the selected prompt.

Element Type  Description
------- ----- -----------------------------------------------
  [1]    N    Display Row if TYPE 0
  [2]    N    Display Column if TYPE 0 (-1 to center message)
  [3]    N    Message TYPE (0-Line, 1-Box, 2-Add to Pull-Down
  [4]    N    Start Row if TYPE 0,1 or Height if TYPE 2
  [5]    N    Start Column if TYPE 0,1 (-1 to center message)
              or Width if TYPE 2
  [6]    N    End Row if TYPE 1
  [7]    N    End Column if TYPE 1

<lReMenu> is used to re-paint the menu after evaluating the
code-block when a menu item is selected.  If .FALSE. and if
<lSticky> is not .TRUE. then the menu will be exited after
the code-block is evaluated.  Use this parameter in place of
<lSticky> to restore the screen before evaluating the code
block and then to repaint the menu after returning from the
code block.

<cHeirArchy> is a single character designating the heirarchal
characteristics of the menu.

------------------------------------------------------------

<lPaintBar> if .TRUE. will only paint the bar items on the
screen and then return.  If .FALSE. (default), then the
menu will be executed.

<aMouseKeys> is a reference to store an array of mouse keys
that match the items on the bar menu.  This parameter is
used in conjunction with <lPaintBar> as a .TRUE. value to
paint the menu-bar, store the coordinates to an array and
then use that array to determine if the mouse was clicked
on the menu bar area.

Notes:

The source-code required to generate a complex pull-down menu can be very complicated especially if the menu needs to support multiple-level pull-downs, message boxes, code-blocks, and help codes, therefore it is recommended that you use the menu-designer, DC_MENUEDIT() or MENU EDIT. This design tool will create and save your menus in the data-dictionary, an array file or source code.

Examples:

  -- Example 1 --

 /* This example demonstrates using DC_MENUMAIN() to return a
    code letter based on a user menu selection */

 local aMenus, aSubMenus, cMenuCode

 aMenus :=  { 'File','Edit','View','Run' }

 aSubMenus :=  { { 'Open File','Close File','e~Xit to Dos' },;
                 { 'Edit File','Save File' },;
                 { 'View File','Print File' },;
                 { 'Run Program','DOS ~Shell'} }

 cMenuCode := ;
   DC_MENUMAIN( { 1, 3, 'bg+/rb,n/bg,w+/bg,w+/r,n+/bg', 'BAD', ;
                .t., 'FO', { aMenus }, { aSubMenus }, 'X' } )
 do case
   case cMenuCode = 'FX' .OR. lastkey()=K_ESC
     quit
   case cMenuCode = 'FO'
     openfile()
   case cMenuCode = 'FC'
     closefile()
   case cMenuCode = 'EE'
     editfile()
   case cMenuCode = 'ES'
     savefile()
   case cMenuCode = 'VS'
     viewfile()
   case cMenuCode = 'VP'
     printfile()
   case cMenuCode = 'RR'
     runexe()
   case cMenuCode = 'RS'
     rundos()
 endcase
 return

 -- Example 2 --

 /* This example demonstrates using DC_MENUMAIN() to execute a
    code block based on a user menu selection */

 local aMenus, aSubMenus, aSubBlocks

 aMenus :=  { 'File','Edit','View','Run' }

 aSubMenus :=  { { 'Open File','Close File','e~Xit to Dos' },;
                 { 'Edit File','Save File' },;
                 { 'View File','Print File' },;
                 { 'Run Program','DOS ~Shell'} }

 aSubBlocks := { { {||openfile()}, {||closefile()}, ;
                 { ||__quit()} },;
                 { {||editfile()}, {||savefile()} },;
                 { {||viewfile()}, {||printfile()} },;
                 { {||runexe()}, {||rundos()} } }

 do while .t.
   DC_MENUMAIN( { 1, 3, 'bg+/rb,n/bg,w+/bg,w+/r,n+/bg', 'CAD', ;
                  .t., 'FO', ;
                  { aMenus }, { aSubMenus, aSubBlocks }, 'X' } )
 enddo
 return

 -- Example 3 --

 /* This example demonstrates loading a menu from the Menu
    Dictionary file and passing it to DC_MENUMAIN() for
    execution */

 local aPreMenu, aMenuMain, cMenuCodes

 aPreMenu := DC_MenuLoad( 'MAINMENU' )
 aMainMenu := DC_MenuCompile( aPreMenu )
 cMenuCodes := DC_MENUMAIN( aMainMenu )

 -- Example 4 --

 /* See the _DCBROW3.PRG source code file for an example of
    building a complex menu using source-code */

 -- Example 5 --

 /* This examples demonstrates using DC_MENUMAIN() in a
    loop, where the menu is attached to the top of a window */

 local aMenus, aSubMenus, cMenuCode, aMainMenu, aMouseKeys

 aMenus :=  { 'File','Edit','View','Run' }

 aSubMenus :=  { { 'Open File','Close File','e~Xit to Dos' },;
                 { 'Edit File','Save File' },;
                 { 'View File','Print File' },;
                 { 'Run Program','DOS ~Shell'} }

 aMainMenu := { 1, 3, 'bg+/rb,n/bg,w+/bg,w+/r,n+/bg', 'BAD', ;
                .t., 'FO', { aMenus }, { aSubMenus }, 'X' }

 /* -- Paint the menu bar and get the mouse coordinates -- */
 DC_MENUMAIN( aMainMenu,.t.,@aMouseKeys )

 do while .t.

   nInkey := DC_Inkey(0)  /* -- Get  a key -- */
   cCode  := UPPER(CHR(nInkey))

   do case

     case nInkey = K_ESC
       exit

     /* -- mouse click -- */
     case nInkey <= -101  .AND. !Empty(DC_MouseKeys(aMouseKeys))

     /* -- Menu key was hit -- */
     case cCode $ 'FEVR'

       cMenuCode := DC_MENUMAIN( aMainMenu,,,cCode )

       do case

         case cMenuCode = 'FO'
           openfile()
         case cMenuCode = 'FC'
           closefile()
         case cMenuCode = 'EE'
           editfile()
         case cMenuCode = 'ES'
           savefile()
         case cMenuCode = 'VS'
           viewfile()
         case cMenuCode = 'VP'
           printfile()
         case cMenuCode = 'RR'
           runexe()
         case cMenuCode = 'RS'
           rundos()

       endcase

    endcase

 enddo

 -- Example 6 --

 /* -- See DC_MENUACCEL() example for an example of using
    DC_MENUMAIN() with accelerator keys and an array of
    numeric return values -- */

Files:

_DCMENU2.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_menupull()
   dc_menuedit()
   dc_menurun()


dc_menuownerdrawdisable()

Disable owner draw menus throughout application

DC_MenuOwnerDrawDisable() is a Get-Set function that disables the OWNERDRAW feature on all menus created with DCMENUBAR or DCSUBMENU commands. It is needed when using the CodeJock SkinFramework.<br><br>

Syntax:

DC_MenuOwnerDrawDisable( [<lDisable>] ) -> lOldDisable

Arguments:

<lDisable> if .TRUE. will disable owner draw on menus.  The
default is .FALSE.

Files:

_dcclass.prg, dclipx.dll

See Also:

   DCMENUBAR
   DCSUBMENU
   dc_menuownerdrawset()


dc_menuownerdrawset()

Sets or resets the ownerdraw flag on menu items

DC_MenuOwnerDrawSet() is used to walk through a menu tree and set or reset the ownerdraw flag on each item.<br><br>This function is used to enable or disable ownerdraw and an existing menu.<br><br>

Syntax:

DC_MenuOwnerDrawSet( <oMenu> , <lSet> ) -> nil

Arguments:

<oMenu> is a menu object created with the DCSUBMENU command or
the DC_XbpMenu() class.

<lSet> if .TRUE. will set the ownerdraw flag on to insure that
all items are drawn using ownerdraw, otherwise the flag will
be set off.

Files:

_dcclass.prg, dclipx.dll

See Also:

   dc_menuownerdrawdisable()


dc_menupick()

Pop up a Pick list of all menus in the Menu Dictionary

DC_MENUPICK() is used to pop-up a pick-list of all Menus in the DCMENU.DBF Menu Dictionary File.<br><br><br><br><br><br><br><br>

Syntax:

DC_MenuPick() -> cMenuName

Returns:

 A character string.

Arguments:

 None.

Examples:

 /* This example demonstrates how to use DC_MENUPICK()
    to pop-up a pick-list of Menus in a DCSAY..GET */

 #include 'dcdialog.ch'

 LOCAL cMenuName := SPACE(8)
 @ 10,10 DCSAY 'Enter Menu Name ' GET cMenuName ;
   POPUP {|c|DC_MenuPick()}

Files:

_DCMENUE.PRG

See Also:

   dc_menuload()
   dc_menuedit()


dc_menupull()

A nested, moused pull-down menu-system

DC_MENUPULL() is a menu-system that creates pull-down, pop-up, or AT..PROMPT style menus with optional "high-lighted" characters, separator lines, "grayed (non-selectable)" items, message lines (or boxes), and optional code-block evaluation and help codes.<br><br> DC_MENUPULL() automatically supports both keyboard and mouse input. If the menu is a pop-up or pull-down menu, then clicking the mouse outside the menu prompt area is equivalent to pressing the escape key. The left button of the mouse is used to select the menu item. Press the ENTER key, the right mouse button, or double-click the left mouse button to invoke the selected item.<br><br> Menus may be "nested" to provide sub-menus and sub-sub-menus.

Syntax:

DC_MenuPull ( <aMenus> ) -> cCodes

Returns:

 If <lReturnVal> is .FALSE. (default) the hot-key character of the
 selected menu item will be returned.  If <lReturnVal> is .TRUE.,
 the CHR() value of the menu choice will be returned.   For example,
 if the 4th menu item is selected, then CHR(4) will be returned.

 A null string is returned if the ESCape key is pressed.

Arguments:

<aMenus> is a multidimensional array of information about
the pull-down menu.

Element  Type  Description (See below)
------- ----  ----------------------------------
  [1]     N    <nRow>
  [2]     N    <nCol>
  [3]     C    <cTitle>
  [4]     C    <cColors>
  [5]     C    <cType>
  [6]     L    <lBar>
  [7]     L    <lRetVal>
  [8]     C    <cExitKey>
  [9]     L    <lRestScreen>
 [10]     L    <lShadow>
 [11]     L    <lSticky>
 [12]     L    <lReMenu>
 [13]     C    <cHeirArchy>
 [14]     A    <aMouseKeys>
 [15]     A    <aMsgOptions>
 [16]     A    <aRowCol>
 [17]     A    <aPrompts>
 [18]     A    <aPromptBlock>
 [19]     A    <aEvalBlocks>
 [20]     A    <aMessage>
 [21]     A    <aHelp>
 [22]     A    <aAccess>
 [23]     A    <aReturns>

<nRow> is the upper-left row (for pull-downs), or lower-left
row (for pop-up menus).

<nCol> is the upper-left column (for pull-downs), or lower-left
column for pop-up menus).

<cTitle> is an Optional title to be displayed centered on the
top or bottom line of the box (depending on if it's a pull-down
or a pop-up box.)  If no title is desired use a null string
("").

<cColors> is a single string of 5 colors (separated by
commas) to be used for the frame, menu items, hi-lited letters,
select bar, grayed items respectively.  If no argument is
passed, then the dCLIP default colors will be used.

<cType) is a single character defining the type of menu:

   A - Pull-down menu
   B - Pop-up menu
   C - Plain menu, no borders (default)

<lBar>  if .TRUE. (default) will make the menu resemble a
MENU TO, with a select bar.  If you do not want a select bar,
and just want the items to be chosen by pressing the hot-key
letter only, set this to .FALSE.

<lRetVal> if .FALSE. (default) will return the hot-key
character of the selected menu item.  If .TRUE., the CHR()
value of the menu choice will be returned.   For example, if
the 4th menu item is selected, then CHR(4) will be returned.
This parameter should also be set to .TRUE. if you are
passing code-blocks to be evaluated and want to return from
the menu after evaluating the code-block.

<cExitKey> is a string containing the character value of any
keys that will exit the menu and return the pressed key value.
The ESCape key always exits.  If any "exit key" is pressed that
is not a menu item "hot key", then the key character value will
be returned.

<lRestScreen> if .TRUE. (default) will restore the previous
screen after exiting the menu.  If .FALSE. the menu and
highlighted selection will remain on the screen.

<lShadow> if .TRUE. (default only if <cType> is "A") will
display a shadow on the menu.

<lSticky> is used to modify the behavior of DC_MENU_P() only
when a selected item has an associated code-block.  If
<lSticky> is true, the code-block will be evaluated while the
menu is still displayed on the screen. If .FALSE., then the
screen will be restored (only if <lRestoreScreen> is .TRUE.)
followed by the evaluation of the code-block.

<lReMenu> is used to re-paint the menu after evaluating the
code-block when a menu item is selected.  If .FALSE. and if
<lSticky> is not .TRUE. then the menu will be exited after
the code-block is evaluated.  Use this parameter in place of
<lSticky> to restore the screen before evaluating the code
block and then to repaint the menu after returning from the
code block.

<cHeirArchy> is a single character designating the heirarchal
characteristics of the menu.

  M - Main Level heirarchy.  This kind of menu will be
      executed at the same level as the calling menu rather
      than calling it as a sub-menu.  Use this option to
      prevent the user from blowing up the call stack.

  S - Sub Level heirarchy (Default).  This kind of menu will
      be called as a sub-level menu and will return to the
      previously called menu.

<aMouseKeys> is a multi-dimensional array of mouse-buttons
to active outside the menu area.  See DC_MOUSEKEY() for
specifications.

<aMsgOptions> is an optional array of options for determining
where and how the message will be displayed.

Element Type  Description
------- ----- -----------------------------------------------
  [1]    N    Display Row if TYPE 0
  [2]    N    Display Column if TYPE 0 (-1 to center message)
  [3]    N    Message TYPE (0-Line, 1-Box, 2-Add to Pull-Down
  [4]    N    Start Row if TYPE 0,1 or Height if TYPE 2
  [5]    N    Start Column if TYPE 0,1 (-1 to center message)
              or Width if TYPE 2
  [6]    N    End Row if TYPE 1
  [7]    N    End Column if TYPE 1

<aRowCol> is an optional ragged array of Row/Column positions
for each item in <aPrompts>.  If a Row/Column array is not
passed then the prompts will be placed vertically starting at
<nRow> and <nCol>.

<aPrompts> is an array of menu prompts to be displayed.  The
first letter of each menu item will be hilited and will be
designated as that menu item's "hot-key".  If a different
hot-key letter is desired for a item, precede the desired
hot-key letter with a tilde (~).   If the item is a
"gray-scale" item (i.e. it displays only but is not
selectable), it must be preceded by an "*" character.  If the
item is a separator line, it must be passed as an "@"
character.  If the item is a separator line with a sub-title,
then it must be passed as a "@" character plus the sub-title
string. "Nesting" of sub-menus is accomplished by passing an
array of sub-menu information rather than a character string.
<aPrompts> may contain any mixture of character strings
(single items) or arrays (nested items).  Selection of a
nested item will pop-up a sub-menu.  To create nested items
pass an array with the following structure:

 Element  Type   Description
 -------  ----   ---------------------------------
   [1]   C     Menu prompt
   [2]   A     Array of sub-menu items
   [3]   A     Array of sub-menu code-blocks (optional)
   [4]     A     Array of sub-menu messages
   [5]     A     Array of sub-menu help codes

<aPromptBlocks> is an optional array of code blocks.  Must be
one code block for each item in <aPrompts>.  If a prompt block
array is passed then the code block will be evaluated when the
item is being painted in the menu and the item will be "grayed"
(non-selectable) if the evaluated code block returns a .FALSE.
If the code block returns a .TRUE. or the array item is a NIL,
then the prompt item is selectable.

<aEvalBlocks> is an optional array of code blocks.  Must be one
code block for each item in <aPrompts>.  If a code block array
is passed then the code block will be evaluated when the item
is selected and the user presses enter.

<aCoord> is an optional ragged array of Row/Column positions
for each item in <aPrompts>.  If a Row/Column array is not
passed then the prompts will be placed vertically starting at
<nRow> and <nCol>.

<aMessage> is an optional array of character-string messages to
be displayed for each item in <aPrompts>.  The message will be
displayed in accordance with the message options defined in
<aMsgOptions>.

<aHelp> is an optional array of character-strings for each item
in <aPrompts>.  The string will be passed as the fourth (4th)
parameter to the HELP procedure if the F1 key is pressed when
an item is selected.  See DC_HELPF1() for more information.

<aAccess> is an optional array of character string access level
codes for each item in <aPrompts>.   The logged on user will not
be allowed access to this item if the DC_USERACCESS() function
returns a logical .FALSE. when passed this access code.  If
the access code is a nil or an empty null-string, or if the
menu is being run with no specific user logged onto the system
or if the user has access to all menus and items, then this
item will be accessible.

<aReturns> is an optional array of numerical return values for
each item in <aPrompts>.  This value will be posted to a
static memory variable (when the menu item is selected ) which
is accessed by the function DC_MENURETURN().

Notes:

The behavior of DC_MENUPULL() depends on the current setting of the DC_WINMODE() function.

This function is provided as a replacement for DC_MENU_P() from earlier versions. DC_MENUPULL() is more powerful and uses much less eval stack memory, therefore it can be called recursively without memory problems.

If a FUNCTION KEY was pressed that was not previously set to call a code-block with SETKEY(), then pressing that function key will cause the value of the key (i.e. -10) to be saved to the static variable to be returned by DC_MENURETURN().

Examples:

 -- Example 1 --

 /* This example demonstrates using DC_MENUPULL() to return a
    code letter based on a user menu selection */

 local aPrompts, cMenuCode

 aPrompts :=  { 'Open File',;
                'Close File',;
                'Edit File',;
                'Save File',;
                'View File',;
                'Print File',;
                'Run Program',;
                'DOS ~Shell'  }

 cMenuCode := ;
   DC_MENUPULL( { 24, 28, ' File Options ', ;
     'bg+/rb,n/bg,w+/bg,w+/r,n+/bg', 'B',,,,,,,,,,,, ;
      aPrompts } )

 do case
   case cMenuCode = 'O'
     openfile()
   case cMenuCode = 'C'
     closefile()
   case cMenuCode = 'E'
     editfile()
   case cMenuCode = 'S'
     savefile()
   case cMenuCode = 'S'
     viewfile()
   case cMenuCode = 'P'
     printfile()
   case cMenuCode = 'R'
     runexe()
   case cMenuCode = 'S'
     rundos()
 endcase
 return

 -- Example 2 --

 /* This example demonstrates using DC_MENU_P() to execute a
    code block  based on a user menu selection */

 local aPrompts, aBlocks

 aPrompts :=  { 'Open File',;
                'Close File',;
                'Edit File',;
                'Save File',;
                'View File',;
                'Print File',;
                'Run Program',;
                'DOS ~Shell'  }

 aBlocks := { {||openfile()},;
              {||closefile()},;
              {||editfile()},;
              {||savefile()},;
              {||viewfile()},;
              {||printfile()},;
              {||runexe()},;
              {||rundos()}     }

 DC_MENUPULL( { 24, 28, ' File Options ', ;
   'bg+/rb,n/bg,w+/bg,w+/r,n+/bg', 'B',,,,,,,,,,,, ;
    aPrompts,, aBlocks } )

 return

 -- Example 3 --

 // This example shows how to "nest" sub-menus.
 // In the below example, selecting item 2 (File Options) of
 // the main menu will pop-up a sub-menu.  Selecting Item 1
 // (Delete a File) will pop-up another sub-menu.  Selecting
 // Item 2 (Binary File) will return "FDB".

 LOCAL aSubPrompt, aSubBlock, aMainPrompt, aSubSubPrompt

 aSubSubPrompt := {'ASCII File','Binary File','EXE File'}

 aSubPrompt := { ;
     {'Delete a file',aDelPrompt},;
      'Copy a file', ;
      'Move a file' }

 aSubBlock  := { , {||copyafile()}, {||moveafile()} }

 aMainPrompt := { ;
    'Edit Options',;
   {'File Options', aSubPrompt, aSubBlock },;
    'Search Options',;
    'Print Options' }

 cSelection := ;
   DC_MENUPULL( { 10, 10,,,'B',,,,,,,,,,,, aMainPrompt } )

Files:

_DCMENU2.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_menumain()


dc_menureversecolor()

Changes the way the color of the selected menu item behaves

DC_MenuReverseColor() is used to change the way the color of the selected menu item behaves. The default is .FALSE. to preserve the look of existing menus. A .TRUE. will cause the foreground and background colors to switch.

Syntax:

DC_MenuReverseColor( [<lReverse>] ) -> lOldReversed

Arguments:

<lReverse> if .TRUE. will reverse the color. .FALSE. is default.

Files:

_DCCLASS.PRG, DCLIPX.DLL

See Also:

   DCMENUBAR
   DCSUBMENU
   DCMENUITEM


dc_menurun()

Run a menu

DC_MENURUN() is used to load a menu from the menu dictionary and execute the menu or to run a menu that is a passed as an array.<br><br> Menu arrays may be top-bar style menus (with pull-downs), just pull-downs, or tree-style menus DC_MENURUN() will determine which type of menu array it is and pass the array to the appropriate menu function for execution.<br><br><br><br><br><br>

Syntax:

DC_MenuRun ( [ <cMenuName> | <aMenu> ], ;
             [ <cCompileKeys> ], ;
             [ <cAccessKeys> ], ;
             [ <oDialog> ] ) -> cCodes

Returns:

 A character string.

Arguments:

<cMenuName> is the name of the menu to load and run.  If
the menu exists in the menu dictionary it will be loaded
and executed.  If the menu does not exist in the dictionary
then an error message will be displayed.  If no parameter is
passed then, a pick-list of menus will be displayed for the
operator to choose.

<aMenu> is a menu array that conforms to the specification
of the array passed to DC_MENUPULL(), DC_MENUMAIN() or
DC_MENUOSYS().

<cCompileKeys> is an optional list of keys (5-digit character
strings separated by commas).  Compile Keys are used for
conditional compiling of menu items based on the COMPILE KEY
item of the menu array.  See DC_MENUCOMPILE() for more
information.

<cAccessKeys> is an optional list of keys (5-digit character
strings separated by commas).  Access Keys are used for
conditional compiling of menu items based on the ACCESS KEY
item of the menu array.  See DC_MENUCOMPILE() for more
information.

<oDialog> is an XbpDialog() style Dialog window to install the
menu.  If this parameter is passed, then it is assumed that the
menu will be GUI.  If <oDialog> is not passed, and the DC_Gui()
flag is ON, a Dialog window will be created and the menu will
be installed in the new dialog window.  If <oDialog> is not
passed and the DC_Gui() flag is OFF, the menu will be run as a
text-style menu in a CRT Window.

Examples:

 -- Example 1 --

 /* --- Run Main Menu from menu-dictionary --- */
 DC_MENURUN( 'MAINMENU' )

 -- Example 2 --

 /* --- Pick a Menu and run it --- */
 DC_MENURUN()

 -- Example 3 --

 /* -- Load a menu, compile and run it -- */

 aPreMenu := DC_MenuLoad('BROWSE')
 aMenu := DC_MenuCompile(aPreMenu)
 DC_MENRUN( aMenu )

Files:

_DCMENUE.PRG

See Also:

   dc_menucompile()
   dc_menuedit()


dc_menuto()

A Moused replacement for MENU TO

DC_MENUTO() is a Dual-mode replacement for _MenuTo(). When the GUI flag is ON, DC_MENUTO() functions similiar to _MenuTo() except that it is displayed in GUI mode. When the GUI flag is OFF, DC_MENUTO() functions identical to _MenuTo() except it is also activated by a mouse. The left button of the mouse is used to select the menu item. The right button or double-clicking works identical to the ENTER key.<br><br> In Text mode, DC_MENUTO() also supports highlighting of special characters to use as "hot-keys".

Syntax:

DC_MenuTo( <nRow>, ;
           <nCol>, ;
           [<cTitle>], ;
           [<cBoxColor>], ;
           [<lType>], ;
           [<lBar>], ;
           [<lReturnVal>], ;
           [<nStart>], ;
           <aItems>, ;
           [<aBlocks>], ;
           [<nExitKey>] ) -> cMenuLetter

Returns:

 The letter corresponding to the Hot-Key assigned to the menu item
 that was selected, a < sign if the left arrow was pressed, a > if
 the right arrow was pressed, or a null string if an error occured.

Arguments:

<nRow> is the upper-left row (for pull-downs), or lower-left
row (for pop-up menus).

<nCol> is the upper-left column (for pull-downs), or lower-left
column (for pop-up menus).

<cTitle> is an Optional title to be displayed centered on the
top line of the box.  If no title is desired use a null string
("").

<cBoxColor> is a single string of four colors to be used for
the frame, menu items, highlighted letters, and select bar,
respectively.

<lType> is .t. for pull-down menu, .f. for pop-up menu

<lBar> - If this is true (.t.) it will make the menu resemble a
MENU TO, with a select bar.  If you do not want a select bar,
and just want the items to be chosen by pressing the hot-key
letter only, set this to false (.f.).

<lReturnVal> - If this is false (.f.), only the hot-key letter
is returned. If this is true (.t.), the entire menu item is
returned.

<nStart> is the number for which menu item to start on.

<aItems> is an array of up to 23 menu items to be displayed.
Each item is a character string.  By default, the first letter
of each menu item will be highlighted and will be designated as
that menu item's "hot-key".  If a different hot-key letter is
desired for a item, precede the desired hot-key letter with a
tilde (~).

If the item is a "gray-scale" item (i.e. it displays only but
is not selectable), it must be preceded by an "*" character.
If the item is a separator line, it must be passed as an "@"
character.  If the item is a separator line with a sub-title,
then it must be passed as a "@" character plus the sub-title
string.

<aBlocks> is an optional parallel array of up to 23 code blocks
to be evaluated.  The code block evaluated will be the one
corresponding to the menu item selected from <aItems>.

<nExitKey> is the INKEY() number of the key to exit the menu
after evaluating the code block.  Default is ESCape key (27).

Notes:

DC_MENUTO() is supported for compatability with previous releases. It will not be supported in future releases. Use DC_MENU_P() instead.

Examples:

 // This example returns a code letter equal to the Hot Key of
 // the selected item

 code := DC_MENUTO( 23, 10,' FILE OPTIONS ', '', .f., .t., ;
         .f., 1, ;
   { 'Select/Open ~Data File',;
     'Select/Open ~Index File',;
     'Open New Data File',;
     '@',;
     'IIF(!EMPTY(ALIAS()),'','*')+'Close Data File',;
     'IIF(!EMPTY(INDEXKEY(0)),'','*')+'Close Index ~File(s)',;
     'Set Default Directory',;
     'Set ~Path Directories' } )

 // This example executes a code block for the selected item.
 // and exits the menu only if ESCape is pressed.

 DC_MENUTO( 23,10, ' UTILITIES ', '', .f., .t., .f., 1,
   { 'Select/Open ~Data File',
     'Select/Open ~Index File',
     'Open New Data File',
     '@',
     'IIF(!EMPTY(ALIAS()),'','*')+'Close Data File',
     'IIF(!EMPTY(INDEXKEY(0)),'','*')+'Close Index ~File(s)' } ,;
      { {||DC_DBFSEL()},;
       {||DC_DBISEL()},;
       {||DC_DBFOPEN()},;
       {||dbCloseArea()},;
       {||dbClearIndex()} }, K_ESC )

Files:

_DCMENU2.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_menumain()


dc_mergeblocks()

Merge two code blocks for later evaluation

DC_MergeBlocks() is used to combine two codeblocks into one code block for later evaluation.<br><br> This function is handy when it is required to add a code block action to a callback slot but not overwrite any code block which may already be assigned, thus allowing both code blocks to be evaluated when the callback event occurs.<br><br>

Syntax:

 DC_MergeBlocks( <bBlock1>, ;
                 <bBlock2> ) -> bNewBlock

Returns:

 A Code Block.

Arguments:

<bBlock1> and <bBlock2> are any code blocks with the following
structure:

{|mp1,mp2,oXbp|...}

Examples:

 oParent:resize := ;
    DC_MergeBlocks(oParent:resize, ;
    _MoveToolBar(oParent,oXbp,nAlign,.t.))

Files:

_DCFUNCT.PRG, DCLIPX.DLL


dc_mergegetlists()

Merge two GetLists into one

DC_MergeGetLists() is used to combine two GetList arrays into a single GetList array. This is required when it is necessary to:<br><br> (1) create two separate dialog windows using DCREAD GUI with the EXIT clause and then combine the GetLists to pass on to the DC_ReadGuiEventLoop() event handler <br><br> (2) add dialog items to an existing dialog and GetList when designing a dialog for optimum performance.<br><br> Only the options assigned to the first GetList will be carried forward to the merged GetLists.

Syntax:

 DC_MergeGetLists( <aGetList1>, ;
                   <aGetList2> ) -> aGetList1

Arguments:

<aGetList1> and <aGetList2> are GetList arrays containing
DC* commands.  The items in <aGetList2> are added to <aGetList1>.

Examples:

FUNCTION XTest()

/* This example shows how to merge to dialogs into one
   with a common GetList and a single event loop */

LOCAL GetList := {}, aGetList1, aGetList2, dDate1 := Date(), ;
      dDate2 := Date() + 2, cName1 := Space(10), cName2 := Space(10), ;
      oDlg1, oDlg2

@ 0,0 DCSAY 'Enter Date 1' GET dDate1 ;
      GETTOOLTIP 'Enter a Valid Start Date'
@ 1,0 DCSAY 'Enter Date 2' GET dDate2 ;
      GETTOOLTIP 'Enter a Valid End Date'

DCREAD GUI FIT ADDBUTTONS EXIT PARENT @oDlg1 SAVE ;
      TITLE 'Enter Date Information'

aGetList1 := GetList

GetList := {}

@ 0,0 DCSAY 'Enter Name 1' GET cName1 ;
      GETTOOLTIP 'Enter a Valid Start Name'
@ 1,0 DCSAY 'Enter Name 2' GET cName2 ;
      GETTOOLTIP 'Enter a Valid End Name'

DCREAD GUI FIT EXIT PARENT @oDlg2 SAVE ;
      TITLE 'Enter Name Information'

oDlg2:setPos( { oDlg1:currentPos()[1], ;
                oDlg1:currentPos()[2] + oDlg1:currentSize()[2]} )

aGetList2 := GetList

GetList := DC_MergeGetLists( aGetList1, aGetList2 )

DC_ReadGuiEventLoop( GetList )

oDlg1:destroy()
oDlg2:destroy()

RETURN nil

--------------------------

FUNCTION XTest2

/* This example demonstrates how to create a dialog that
   builds objects and adds items to the GetList on demand
   rather than all at once.  This improves performance
   by creating the objects only when they are needed.
   The Gets on a Tab Page will be created the first time
   the respective Tab Page is selected and only if it
   is selected. */

LOCAL GetList := {}, aTabPages[8], aGets[8,20], i, j, aBuildGets[8], ;
      GetOptions

AFill(aBuildGets,.t.)
FOR i := 1 TO 8
  IF i = 1
    @ 0,0 DCTABPAGE aTabPages[i] SIZE 80,23 ;
          CAPTION 'Page ' + Alltrim(Str(i)) PREOFFSET 0 POSTOFFSET 90 ;
          EVAL BuildBlock(aTabPages,aBuildGets,i,GetList,aGets)

  ELSE
    @ 0,0 DCTABPAGE aTabPages[i] RELATIVE aTabPages[i-1] ;
          CAPTION 'Page ' + Alltrim(Str(i)) ;
          GOTFOCUS BuildBlock(aTabPages,aBuildGets,i,GetList,aGets)
  ENDIF
NEXT

DCREAD GUI FIT TITLE 'Tab Pages full of Data'

RETURN nil

* ------------------

STATIC FUNCTION BuildBlock( aTabPages, aBuildGets, i, GetList, aGets )

RETURN {||BuildGets(aTabPages,aBuildGets,i,GetList,aGets)}

* ------------------

STATIC FUNCTION BuildGets( aTabPages, aBuildGets, i, aGetList, aGets )

LOCAL j, GetOptions, GetList := {}

IF aBuildGets[i]

  aBuildGets[i] := .f.
  FOR j := 1 TO 20
    aGets[i,j] := Pad('This is the data in Get ' + ;
       Alltrim(Str(i)) + '/' + Alltrim(Str(j)),40)
    @ j+1, 5 DCSAY 'This is Say ' + ;
       Alltrim(Str(i)) + '/' + Alltrim(Str(j)) ;
       GET aGets[i,j] PARENT aTabPages[i] ;
       SAYSIZE 15
  NEXT
  DCREAD GUI PARENT aTabPages[i] EXIT SAVE
  DC_MergeGetLists(aGetList,GetList)

ENDIF

RETURN nil

Files:

_DCGETBX.PRG, DCLIPX.DLL


dc_messageoff()

Display a blinking message in a GUI message box

DC_MessageOff() is used to terminate a message thread that was created with DC_MessageOn().

Syntax:

DC_MessageOff ( <aMessage> ) -> lStatus

Returns:

A logical .TRUE. if the message was terminated properly, a .FALSE.
it an error occurred.

Arguments:

<aMessage> is an array that was returned by DC_MessageOn().

Files:

_DCEXPL.PRG, DCLIPX.DLL

See Also:

   dc_messageon()
   dc_messageoptions()
   dc_messageparent()


dc_messageon()

Display a blinking message in a GUI message box

DC_MessageOn() is used to display a message in an XbpStatic() object at a specified blinking rate. DC_MessageOn() starts a new thread to cause the message to blink until it is removed with DC_MessageOff().

Syntax:

DC_MessageOn ( <bcMessage>, ;
               [<oParent>], ;
               [<nBlink>], ;
               [<nColor>], ;
               [<cFont>], ;
               [<nMode>], ;
               [<nTimeOut>] ) -> aMessage

Returns:

An array containing information needed to destroy the thread and
terminate the message blinking.

Arguments:

<bcMessage> is the message to display.  This may be a character
string or a code block that returns a character string.  If it is
a code block, then the code block is evaluated at the blink rate.
<nBlink>.  If <nBlink> is 0, then the code block is evaluated each
1/10 second.

<oParent> is a pointer to the XbpStatic() object that will display
the message.  If this parameter is not passed, then the function
DC_MessageParent() must be called first to establish a receiving
object.  The object may be any class of object that supports the
:setCaption(), :setFontCompoundName() and :setColorFG() methods.

<nBlink> is the blink rate, in 1/100 seconds.  The default is 0
(meaning no blinking).  If this parameter is not passed then the
blink rate is established by the DC_MessageOptions() default
value.

<nColor> is the foreground color of the message.  This must be
a numeric value starting with GRA_CLR_* as defined in GRA.CH or
the numeric equivalent of an RGB color.  The color of the message
object will be temporarily changed for this message only.

<cFont> is the font of the message.  This must be a valid font
string (eg. "10.Arial Bold").  The font of the message object
will be temporarily changed for this message only.

<nMode> is reserved.

<nTimeOut> is the timeout (in seconds) of the message blinking
thread.  The default is 0 (meaning no timeout).  Normally a
timeout is not needed provided that DC_MessageOff() is called to
terminate the thread.  A timeout may be desirable in the event
that an error may occur which prevents DC_MessageOff() from
being called.

Examples:

#include "dcdialog.ch"

FUNCTION XTest()

LOCAL n, GetList[0], oMsgBox, oDialog, aMessage

@0,0 DCSTATIC TYPE XBPSTATIC_TYPE_TEXT SIZE 100,2 ;
     FONT '8.Arial Bold' COLOR GRA_CLR_BLUE, GRA_CLR_WHITE ;
     OBJECT oMsgBox OPTIONS XBPSTATIC_TEXT_CENTER + XBPSTATIC_TEXT_BOTTOM

DCREAD GUI FIT EXIT PARENT @oDialog TITLE 'Message Test' OPTIONS GetOptions

DC_MessageParent(oMsgBox)
DC_MessageOptions( { 0, 10, 2 } )

aMessage := DC_MessageOn( 'Indexing File B')
MyReindex('B')
DC_MessageOff(aMessage)

aMessage := DC_MessageOn( 'Indexing File C', oMsgBox, 5, ;
            GRA_CLR_RED, '30.Courier Bold' )
MyReindex('C')
DC_MessageOff(aMessage)

aMessage := DC_MessageOn( 'Indexing File D', oMsgBox )
MyReindex('D')
DC_MessageOff(aMessage)

aMessage := DC_MessageOn( 'Indexing File E', oMsgBox, 5,,,, 2 )
MyReindex('E')
DC_MessageOff(aMessage)

oDialog:destroy()

DC_MsgBox('done')

RETURN nil

Files:

_DCEXPL.PRG, DCLIPX.DLL

See Also:

   dc_messageoff()
   dc_messageoptions()
   dc_messageparent()


dc_messageoptions()

Set the default options for DC_MessageOn()

DC_MessageOptions() is used to set default options for DC_MessageOn().

Syntax:

DC_MessageOptions ( <aOptions> ) -> aOldOptions

Returns:

An array containing the previously set options.

Arguments:

<aOptions> is an array of options.

Element  Type  Description
-------  ----  ---------------------------------------------
  [1]      N   Mode (reserved)
  [2]      N   Blink rate (1/100 seconds)
  [3]      N   Time out (seconds)
  [4]      L   Clear message window on close

Examples:

aOptions := Array(4)

aOptions[2] := 30
aOptions[3] := 100
aOptions[4] := .t.

DC_MessageOptions(aOptions)

Files:

_DCEXPL.PRG, DCLIPX.DLL

See Also:

   dc_messageon()
   dc_messageoff()
   dc_messageparent()


dc_messageparent()

Set the Parent object for DC_MessageOn()

DC_MessageParent() is used to set the default parent object for DC_MessageOn().

Syntax:

DC_MessageOptions ( [<oParent>] ) -> oOldParent

Returns:

The previously set parent object.

Arguments:

<oParent> is an XbpStatic() object or any object that supports
the methods :setCaption(), :setColorFG() and :setFontCompoundName().

Files:

_DCEXPL.PRG, DCLIPX.DLL

See Also:

   dc_messageon()
   dc_messageoff()
   dc_messageoptions()


dc_modstru()

Modify the structure of a database

DC_MODSTRU() is used to change the structure of the database in the current work area and restore all the data in the file or save the database to a new name.<br><br> You can add perform the following operations with a GUI dialog:<br><br> 1. Add a new field 2. Delete a field 3. Move a field 4. Rename a field 5. Replicate a set of new fields 6. Change the type of a field 7. Change the length of a field<br><br> All data in the former file will restored to the modified file except for any fields that were deleted.<br><br>

Syntax:

 DC_ModStru( [<cNewFileName>] ) -> lStatus

Returns:

 A logical .TRUE. if the file was successfully updated, .FALSE.
 if the operation was aborted by the user or otherwise failed.

Arguments:

<cNewFileName> is the name to assign to the new modified file.
If no argument is given, then the new file name will be the
same as the original and the original file will be renamed to
the same name as the file alias with a .DBK extension.  If the
file contained at least one memo field, then the memo file
will be renamed to the same name as the file alias with the
.DTK extension.

Examples:

 do while .t.
   @ 10,10 prompt "open a database"
   @ 11,10 prompt "browse database"
   @ 12,10 prompt "modify structure"
   menu to nChoice
   do case
     case nChoice = 1
       dc_dbfopen()
     case nChoice = 2
       dc_browsedb()
     case nChoice = 3
       DC_MODSTRU()
   endcase
 enddo

Files:

_DCFCSTR.PRG, DCLIP1.DLL

See Also:

   dc_struupdate()


dc_moubutton()

Test the status of the mouse buttons

DC_MOUBUTTON() returns the status of the mouse buttons.

Syntax:

DC_MouButton ( ) -> nStatus

Returns:

 A numeric value.

  0 - All buttons up
  1 - Left button down
  2 - Right button down
  3 - Left and Right button down
  4 - Right button released

Arguments:

 None

Examples:

 FUNCTION key_mouse ( nMouseRow, nMouseCol )

 // Get a key or mouse event
 // returns -100 is left button down, 13 if right button
 // released
 do while .t.
   nInkey := inkey()
   nMouseStatus := DC_MOUBUTTON()
   do case
     case nMouseStatus = 1
       dc_mougetposition( @nMouseRow, @nMouseCol )
       nInkey := -100
       exit
     case nMouseStatus = 4
       nInkey := 13
       exit
     case nInkey # 0
       exit
   endcase
 enddo
 return nInkey

Files:

_DCMOUSE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_mousekey()


dc_mouclick()

Set the mouse button double-click delay

DC_MOUCLICK() is used to set the delay between successive clicks of the left button to determine whether or not the operator has "double-clicked" the button. DC_MOUCLICK() works in conjunction with DC_MOUBUTTONSTATUS() and DC_INKEY(). DC_MOUBUTTONSTATUS() returns a 2 when the right button is pressed or the left button is double-clicked. DC_INKEY() returns a -104 when the right button is pressed or the left button is double-clicked.

Syntax:

DC_MouClick ( <nDelay> ) -> nDelay

Returns:

 A numeric value.

  0 - All buttons up
  1 - Left button down
  2 - Right button down
  3 - Left and Right button down
  4 - Right button released

Arguments:

<nDelay> is a number representing tenths of a second to wait
for successive depressions of the left button.  Default is 4.
If nDelay is set to 0, then the double-click action will be
disabled.

Examples:

 // Set double-click delay to 3. seconds.
 DC_MOUCLICK( .3 )

Files:

_DCMOUSE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_inkey()


dc_moucol()

Get current screen column of mouse cursor

DC_MOUCOL() returns the column location of the mouse cursor.

Syntax:

DC_MouCol () -> nColumn

Returns:

 A numeric value

Arguments:

 None

Examples:

 nRow := nil
 nCol := nil
 GetMouse( @nRow, @nCol )
 ? 'Mouse position is:', nRow, nCol
 return

 function GetMouse ( @nRow, @nCol )
 nRow := dc_mourow()
 nCol := DC_MOUCOL()
 return nil

Files:

_DCMOUSE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_mourow()
   dc_mougetpos()


dc_moudisable()

Disable the mouse functions

DC_MOUDISABLE() is used to temporarily disable mouse functions. The default after DC_MOUINITIALIZE() is called at the start of the application is "enabled". DC_MOUDISABLE() and DC_MOUENABLE() are used in conjunction with each other if you wish to disable mouse capability only in certain areas of the program and reinstate it again without reinitializing.

Syntax:

DC_MouDisable ( ) -> lStatus

Returns:

 A logical .TRUE. if the mouse driver is installed and initialized,
 .FALSE. otherwise.

Arguments:

 None.

Examples:

 dc_moudisable()   // shut off the mouse
 do myapp
 DC_MOUENABLE()    // turn the mouse back on whenever mouse
                   // functions are called

Files:

_DCMOUSE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_mouenable()


dc_mouenable()

Enable the mouse functions

DC_MOUENABLE() is used to enable mouse functions. This is the default after DC_MOUINITIALIZE() is called at the start of the application. DC_MOUDISABLE() and DC_MOUENABLE() are used in conjunction with each other if you wish to disable mouse capability only in certain areas of the program and reinstate it again without reinitializing.

Syntax:

DC_MouEnable ( ) -> lStatus

Returns:

 A logical .TRUE. if the mouse driver is installed and initialized,
 .FALSE. otherwise.

Arguments:

 None.

Examples:

 dc_moudisable()   // shut off the mouse
 do myapp
 DC_MOUENABLE()    // turn the mouse back on whenever mouse
                   // functions are called

Files:

_DCMOUSE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_moudisable()


dc_mougetevent()

Get a mouse event from the Mouse Click buffer

DC_MOUGETEVENT() is used to remove the status of a mouse event from the mouse click buffer.<br><br> DC_MOUSTART() maintains a queue of outstanding mouse events, i.e., events which the Clipper program has not enquired about. The DC_MOUNUMEVENTS(), DC_MOUGETEVENT(), DC_MOUROW(), and DC_MOUCOL() functions all operate on this queue.<br><br> DC_MOUSTART() starts monitoring for mouse clicks and stuffs a key into the keyboard buffer each time a mouse button is pressed and released. The mouse button status is also stuffed into a mouse click buffer for extracting with DC_MOUGETEVENT().

Syntax:

dc_mougetevent ( ) -> nStatus

Returns:

 nil

Arguments:

 None

Notes:

A numeric value, encoded as follows:

0 - No event, queue is empty. 2 - Left button pressed 4 - Left button released 8 - Right button pressed 16 - Right button released

Examples:

 dc_mouinitialize()
 dc_moustart( -29 )  // Key CTRL-F10 is reserved for the mouse
 dc_moushow()
 set key -29 to myfunc

 memo = memoread('dclip.sys')
 memo := memoedit( memo, 5,5,20,75 )

 dc_moustop()
 dc_mouhide()
 set key -29 to
 return

 function myfunc

 local nStatus := DC_MOUGETEVENT()
 @ 23, 0 say ''
 do case
   case nStatus = 2
     ?? '  left button pressed'
   case nStatus = 4
     ?? ' left button released'
   case nStatus = 8
     ?? ' right button pressed'
   case nStatus = 16
     ?? 'right button released'
 endcase
 ?? ' at row', dc_mourow(), ', col', dc_moucol()
 return nil

Files:

_DCMOUSE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_moustart()


dc_mougetpos()

Get the current row and column of the mouse

DC_MOUGETPOS() is used to get the current row and column position of the mouse.

Syntax:

dc_mougetpos ( @<nRow>, ;
               @<nCol> ) -> nil

Returns:

 nil

Arguments:

<nRow> is an integer variable to store the mouse row

<nCol> is an integer variable to store the mouse column

Examples:

 FUNCTION key_mouse ( nMouseRow, nMouseCol )

 // Get a key or mouse event
 // returns -100 is left button down, 13 if right button
 // released
 do while .t.
   nInkey := inkey()
   nMouseStatus := dc_moubutton()
   do case
     case nMouseStatus = 1
       DC_MOUGETPOS( @nMouseRow, @nMouseCol )
       nInkey := -100
       exit
     case nMouseStatus = 4
       nInkey := 13
       exit
     case nInkey # 0
       exit
   endcase
 enddo
 return nInkey

Files:

_DCMOUSE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_moucol()
   dc_mourow()


dc_mouhide()

Hide the mouse cursor

DC_MOUHIDE() is used to hide the mouse cursor, but still leave the mouse enabled to monitor mouse clicks in the event that the user's program is displaying it's own cursor.

Syntax:

dc_mouhide () -> nil

Returns:

 nil

Arguments:

 None

Examples:

 nRow := nil
 nCol := nil
 DC_MOUHIDE()
 // hide the mouse and track it with the screen cursor instead
 set cursor on
 do while .t.
   dc_mougetpos( @nRow, @nCol )
   @ nRow, nCol SAY ''
 endif
 return

Files:

_DCMOUSE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_moushow()


dc_mouinitialize()

Initialize the mouse functions

DC_MOUINITIALIZE() is used to enable all the DC_MOU*() functions. If the mouse is not initialized then all DC_MOU*() functions will return NIL or 0 values.<br><br> DC_MOUINITIALIZE() resets the mouse, hides the mouse cursor, and positions the mouse cursor to the center of the screen.<br><br>

Syntax:

dc_mouinitialize ( ) -> nil

Arguments:

 None

Files:

_DCMOUSE.PRG/.OBJ, DCLIPX.LIB


dc_moupresent()

Is a mouse present?

DC_MOUPRESENT() is used to determine if a mouse driver is present.

Syntax:

dc_moupresent ( ) -> lStatus

Arguments:

 None

Examples:

 if DC_MOUPRESENT()
    dc_mougetpos( @nRow, @nCol )
    ? 'mouse is at ', nRow, nCol
 else
    ? 'No mouse found..  Make sure driver is loaded'
 endif

Files:

_DCMOUSE.PRG/.OBJ, DCLIPX.LIB


dc_mourow()

Get current screen row of mouse cursor

DC_MOUROW() returns the row location of the mouse cursor.

Syntax:

dc_moucol () -> nColumn

Returns:

 A numeric value

Arguments:

 None

Examples:

 nRow := nil
 nCol := nil
 GetMouse( @nRow, @nCol )
 ? 'Mouse position is:', nRow, nCol
 return

 function GetMouse ( @nRow, @nCol )
 nRow := DC_MOUROW()
 nCol := dc_moucol()
 return nil

Files:

_DCMOUSE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_moucol()
   dc_mougetpos()


dc_mousebutton()

Paint a mouse button on the screen

DC_MOUSEBUTTON() is used to paint a button on the screen and add the button to an array for later evaluating with DC_MOUSEKEY().

Syntax:

DC_MouseButton( @<aButtons>, ;
                <nStRow>, ;
                <nStCol>, ;
                <nEnRow>, ;
                <nEnCol>, ;
                <aText>, ;
                <xKeys>, ;
                <nAltKey>, ;
                [<nWait>], ;
                [<cColor>], ;
                [<lBox>] ) -> aButtons

Returns:

 A pointer to the array passed as <aButtons>.

Arguments:

<aButtons> is a the multi-dimensional array that will hold
the mouse button information.  This array must conform to
the specifications for DC_MOUSEKEY().

<nStRow>, <nStCol>, <nEnRow>, <nEnCol> are the screen
coordinates of the mouse button.

<aText> is an array of character strings to display in the
box.  The first line of text will display in the first open
row of the box, etc.

<xKeys> may be a Type C, N, or B.

If type C, then this is a string to stuff into the keyboard
buffer.  If type N, then this is an INKEY() value to stuff
into the keyboard buffer.  If type B, then this is a code
block to evaluate.

<nAltKey> is an Alternate INKEY() value to stuff in the
keyboard buffer after evaluating the code block.

<nWait> is the number of seconds to pause (optional).  Use
this parameter to specify the amount of delay between key
stuffings when the operator holds down the mouse button.

<cColor> is the color of the button.  This must be a
standard Clipper color string.  If no parameter is passed,
the currently selected system color will be used.

<lBox> if .TRUE. (default) will paint a box around the button
and the text will be inserted within the box.  If .FALSE., then
the text will be painted at the starting coordinate and no box
will be painted.

Examples:

 //paint some calculator buttons
 aMouseKeys := {}
 DC_MOUSEBUTTON( @aMouseKeys, nStRow+4, nStCol+2, nStRow+6,;
                 nStCol+5, {'AC'}, 'AC' )
 DC_MOUSEBUTTON( @aMouseKeys, nStRow+4, nStCol+7, nStRow+6,;
                 nStCol+10, {' 7'}, '7' )
 DC_MOUSEBUTTON( @aMouseKeys, nStRow+4, nStCol+11, nStRow+6,;
                 nStCol+14, {' 8'}, '8' )
 DC_MOUSEBUTTON( @aMouseKeys, nStRow+4, nStCol+15, nStRow+6,;
                 nStCol+18, {' 9'}, '9' )
 DC_MOUSEBUTTON( @aMouseKeys, nStRow+4, nStCol+20, nStRow+6,;
                 nStCol+23, {' /'}, '/' )

Files:

_DCMOUSE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_mousekey()


dc_mousekey()

Scan array of mouse buttons and stuff keyboard or evaluate

DC_MOUSEKEY() will scan an array of mouse button definitions and stuff the keyboard or evaluate a code-block with a pre-defined value if the mouse was clicked in a designated area.

Syntax:

DC_MouseKey( <aButtons>, ;
             <lStuff> ) -> cCode

Returns:

 The CHR() value in element 5 of the <aButtons> array if
 the mouse was clicked in the coordinate area.  If the mouse
 was not clicked in an area designated by one of the sub-
 arrays, a null "" string will be returned.

Arguments:

<aButtons> is a multi-dimensional array with coordinates and
Keyboard Codes, Inkey values or Code Blocks for establishing
mouse buttons.  Each button in the main array is a sub-array of
7 elements:

Element   Type   Description
-------   ----   ---------------------------------
  1        N     Top Row of button
  2        N     Left Column of button
  3        N     Bottom Row of button   (optional)
  4        N     Right Column of button (optional)
  5        C     Keyboard character to stuff
          or N   Keyboard INKEY value to stuff
          or B   Code block to evaluate
  6        N     Secondary INKEY value to stuff (optional)
  7        N     Number of seconds to pause (optional).  Use
                 this parameter to specify the amount of
                 delay between key stuffings when the
                 operator holds down the mouse.

If Element 3 is a NIL, then the value of Element 1 will be
used.

IF Element 4 is a NIL, then the value of Element 2 will be
used.

<lStuff> if .TRUE. (default) will stuff the keyboard character
into the keyboard buffer if the mouse was clicked in the button
coordinate area defined by elements 1-4.  If .FALSE. the value
of element 5 will be returned only, not stuffed in the
keyboard.

Examples:

 @ 10,0 to 12,6
 @ 11,2 SAY CHR(24)+' '+CHR(25)
 @ 10,20 to 12,25
 @ 11,21 say 'Kill'
 @ 10,40 to 12,45
 @ 11,41 say 'Add'
 @ 10,60 to 12,65
 @ 11,61 say 'Quit'

 aButtons := { { 10,20,12,25,'K' },;
               { 10,40,12,45,'A' },;
               { 10,60,12,65,K_ESC },;
               { 10,2,,,K_UP,,.5 },;
               { 10,4,,,K_DOWN,,.5 } }

 do while .t.
   nInkey := dc_inkey(0)
   do case
     case nInkey = -101 .AND !empty(DC_MOUSEKEY(aButtons))
     case nInkey = 'K'
       do kill
     case nInkey = 'A'
       do add
     case nInkey = K_UP
       skip -1
     case nInkey = K_DOWN
       skip
     case nInkey = K_ESC
       exit
   endcase
 enddo

Files:

_DCMOUSE.PRG/.OBJ, DCLIPX.LIB


dc_mousetpos()

Set the current row and column of the mouse

DC_MOUSETPOS() is used to set the current row and column position of the mouse.

Syntax:

dc_mousetpos ( <nRow>, ;
               <nCol> ) -> nil

Returns:

 nil

Arguments:

<nRow> is an integer variable to set the mouse row

<nCol> is an integer variable to set the mouse column

Examples:

 // make sure the mouse is at the upper left corner when
 // starting the drag
 DC_MOUSETPOSITION( 10, 20 )
 dc_drag ( 10, 20, 22, 70 )

Files:

_DCMOUSE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_mougetpos()


dc_moushow()

Show the mouse at it's current screen position

DC_MOUSHOW() displays the mouse cursor on the screen, leaving the mouse enabled.

Syntax:

dc_moushow ( ) -> nil

Returns:

 nil

Arguments:

 None

Examples:

 if dc_moupresent()
   dc_mouinitialize()
   MOU_SHOW()
 else
   ? 'Mouse not present'
 endif

Files:

_DCMOUSE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_mouhide()


dc_moustart()

Enable automatic keyboard stuffing on a Mouse Click

DC_MOUSTART() maintains a queue of outstanding mouse events, i.e., events which the Clipper program has not enquired about. The DC_MOUNUMEVENTS(), DC_MOUGETEVENT(), DC_MOUROW(), and DC_MOUCOL() functions all operate on this queue.<br><br> DC_MOUSTART() starts monitoring for mouse clicks and stuffs a key into the keyboard buffer each time a mouse button is pressed and released. The mouse button status is also stuffed into a mouse click buffer for extracting with DC_MOUGETEVENT(). DC_MOUSTART() is handy when using Clipper functions that wait for a key hit such as __WAIT(), ACHOICE(), READMODAL(), MEMOEDIT(), etc, and you wish to call a user-defined function when a mouse-button is clicked.<br><br>

Syntax:

dc_moustart( <nInkey> ) -> nil

Returns:

 nil

Arguments:

<nInkey> is the INKEY value of the key to be placed into the
keyboard buffer when a mouse event occurs.

Examples:

 dc_mouinitialize()
 DC_MOUSTART( -29 )  // Key CTRL-F10 is reserved for the mouse
 dc_moushow()
 set key -29 to myfunc

 memo = memoread('dclip.sys')
 memo := memoedit( memo, 5,5,20,75 )

 dc_moustop()
 dc_mouhide()
 set key -29 to
 return

 function myfunc

 local nStatus := dc_mougetevent()
 @ 23, 0 say ''
 do case
   case nStatus = 2
     ?? '  left button pressed'
   case nStatus = 4
     ?? ' left button released'
   case nStatus = 8
     ?? ' right button pressed'
   case nStatus = 16
     ?? 'right button released'
 endcase
 ?? ' at row', dc_mourow(), ', col', dc_moucol()
 return nil

Files:

_DCMOUSE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_moustop()
   dc_mougetevent


dc_moustop()

Turn off the Mouse Event driver

DC_MOUSTOP() is used to disable mouse events that were started with DC_MOUSTART(). This function must be called when exiting mouse handling routines to insure that mouse clicks don't go into the keyboard buffer when not desired.

Syntax:

dc_moustop ( ) -> nil

Returns:

 Nil

Arguments:

 None.

Examples:

 dc_mouinitialize()
 dc_moustart( -29 )  // Key CTRL-F10 is reserved for the
                     // mouse
 dc_moushow()
 set key -29 to myfunc

 memo = memoread('dclip.sys')
 memo := memoedit( memo, 5,5,20,75 )

 DC_MOUSTOP()
 dc_mouhide()
 set key -29 to
 return

 function myfunc

 local nStatus := dc_mougetevent()
 @ 23, 0 say ''
 do case
   case nStatus = 2
     ?? '  left button pressed'
   case nStatus = 4
     ?? ' left button released'
   case nStatus = 8
     ?? ' right button pressed'
   case nStatus = 16
     ?? 'right button released'
 endcase
 ?? ' at row', dc_mourow(), ', col', dc_moucol()
 return nil

Files:

_DCMOUSE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_moustart()


dc_mouvisible()

Is the mouse cursor visible?

DC_MOUVISIBLE() is used to determine if the mouse cursor is visible on the screen.

Syntax:

dc_mouvisible ( ) -> lStatus

Returns:

 A logical .TRUE. if the mouse is visible, .FALSE. otherwise.

Arguments:

 None

Files:

_DCMOUSE.PRG/.OBJ, DCLIPX.LIB


dc_movecursortoobject()

Move mouse cursor to the center of an object

DC_MoveCursorToObject() will position the mouse cursor to the center of an Xbase Parts object.

Syntax:

DC_MoveCursorToObject( <oXbp> ) -> nil

Returns:

Nil.

Arguments:

<oXbp> is the object to receive the cursor.

Notes:

CAUTION:

1. Moving the cursor to an object that is hidden could cause your mouse to disappear.

2. Moving the cursor to an object that is off the screen could cause your mouse to leap off your desktop and may cause damage. Donnay Software is not responsible for such damage.

3. Moving the cursor to an object that is a large distance from the current location could cause the mouse to shift laterally at near "warp speed". If your hand is on the mouse when this movement occurs, it could cause injury. Donnay Software is not responsible for personal injury.

Files:

_DCFUNCT.PRG, DCLIPX.DLL


dc_moveobject()

Move or resize an Xbase Parts object with the mouse

DC_MOVEOBJECT() is used to dynamically move or resize an object in a Dialog window with the mouse. An optional GRID is displayed in the drawing area of the parent object to make it simple to align the objects on the screen. <br><br>

Syntax:

DC_MoveObject ( <oXbp>, ;
                <aPos>, ;
                <nDragMode>, ;
                <nCursor>, ;
                <aDesign>, ;
                <nStopEvent>, ;
                <nGridRows>, ;
                <nGridCols> ) -> nil

Returns:

 nil.

Arguments:

<oXbp> is a pointer to the object to move or resize.

<aPos> is a two-element array containing the current mouse
coordinates relative to location 0,0 (bottom-left) of the
object.

<nDragMode> is a number defined in DCDIALOG.CH designating
how to drag the object. <nCursor> is the resource number of
a mouse POINTER that has been linked to the .EXE of the
application.  DCCURSOR.CH lists the defines for pointers that
are available EXPRESS.RES.  When using the DESIGN feature of
DC_READGUI() in eXPress++, the following pointers are used.

  Drag Mode                  Cursor Pointer
 -----------------------    --------------------------
 DRAG_ENTIRE_OBJECT         POINTER_ARROW_1
 DRAG_RIGHT                 POINTER_SIZE3_1
 DRAG_RIGHT_TOP             POINTER_SIZE1_2
 DRAG_RIGHT_BOTTOM          POINTER_SIZE2_1
 DRAG_LEFT                  POINTER_SIZE3_1
 DRAG_LEFT_TOP              POINTER_SIZE2_1
 DRAG_LEFT_BOTTOM           POINTER_SIZE1_1
 DRAG_TOP                   POINTER_SIZE4_1
 DRAG_BOTTOM                POINTER_SIZE4_1

<aDesign> and <nStopEvent> are reserved for internal calls.
Pass a NIL.

<nGridRows> and <nGridCols> are the number for pixels for
columns and rows respectively.  Moving and object will cause it
to snap to the grid.

Examples:

 #include 'dcdialog.ch'
 #include 'dccursor.ch'
 #include 'appevent.ch'

 PROCEDURE Xtest( )

 LOCAL GetList := {}, cGet1 := 'This is GET 1', ;
       cGet2 := 'This is GET 2', cMemo := 'This is a memo', ;
       lDesignMode := .f.

 @ 0,0 DCSAY 'This is SAY 1' GET cGet1
 @ 3,0 DCSAY 'This is SAY 2' GET cGet2

 @ 5,0 DCMULTILINE cMemo SIZE 40,5

 @ 12,0 DCPUSHBUTTON CAPTION 'Design' ;
   SIZE 9,1.5 ;
   ACTION {||lDesignMode := .t.}

 DCREAD GUI ;
   FIT ;
   ADDBUTTONS ;
   HANDLER myHandler ;
   REFERENCE @lDesignMode

 RETURN

 /* -------------------- */

 STATIC FUNCTION ;
   myHandler ( nEvent, mp1, mp2, oXbp, oDlg, GetList, lDesignMode )

 LOCAL nWidth, nHeight

 STATIC nCursor := POINTER_ARROW_1, nDragMode := 0

 IF lDesignMode .AND. nEvent = xbeM_Motion

    nWidth := oXbp:CurrentSize()[1]
    nHeight := oXbp:CurrentSize()[2]
    IF oXbp == oDlg .OR. oXbp == oDlg:drawingArea .OR. ;
       Upper(oXbp:ClassName()) == 'XBPTABPAGE'
      nCursor := POINTER_ARROW_1
    ELSEIF mp1[1] >= nWidth - 5 .AND. mp1[2] >= nHeight - 5
      nDragMode := DRAG_RIGHT_TOP
      nCursor := POINTER_SIZE1_1
    ELSEIF mp1[1] >= nWidth - 5 .AND. mp1[2] <= 5
      nDragMode := DRAG_RIGHT_BOTTOM
      nCursor := POINTER_SIZE2_1
    ELSEIF mp1[1] <= 5 .AND. mp1[2] >= nHeight - 5
      nDragMode := DRAG_LEFT_TOP
      nCursor := POINTER_SIZE2_1
    ELSEIF mp1[1] <= 5 .AND. mp1[2] <= 5
      nDragMode := DRAG_LEFT_BOTTOM
      nCursor := POINTER_SIZE1_1
    ELSEIF mp1[1] <= 5
      nDragMode := DRAG_LEFT
      nCursor := POINTER_SIZE3_1
    ELSEIF mp1[1] >= nWidth - 5
      nDragMode := DRAG_RIGHT
      nCursor := POINTER_SIZE3_1
    ELSEIF mp1[2] <= 5
      nDragMode := DRAG_BOTTOM
      nCursor := POINTER_SIZE4_1
    ELSEIF mp1[2] >= nHeight - 5
      nDragMode := DRAG_TOP
      nCursor := POINTER_SIZE4_1
    ELSE
      nDragMode := DRAG_ENTIRE_OBJECT
      nCursor := POINTER_MOVE_1
    ENDIF
    IF IsMethod(oXbp,'SetPointer')
      oXbp:SetPointer( nil, nCursor, 1 )
    ENDIF

    RETURN DCGUI_IGNORE

  ELSEIF lDesignMode .AND. nEvent = xbeM_LbDown

    DC_MoveObject( oXbp, mp1, nDragMode, nCursor )

    RETURN DCGUI_IGNORE

 ENDIF

 RETURN DCGUI_NONE

Files:

_DCFUNCT.PRG/.OBJ, DCLIPX.DLL, DCLIPX.LIB

See Also:

   dc_readgui()


dc_moveparentwindow()

Move a parent window by clicking mouse on child object

DC_MoveParentWindow() is used to move the parent window with the mouse by clicking on a child object at any level.<br><br>

Syntax:

DC_MoveParentWindow( <mp1>, ;
                     <mp2>, ;
                     <oXbp> ) -> nil

Arguments:

<mp1>, <mp2> and <oXbp> are the parameters passed to the
code block.

Notes:

Example: oStatic:lbDown := {|a,b,c|DC_MoveParentWindow(a,b,c)}

Clicking the left button on oStatic will allow movement of theentire window until the mouse is released.

Files:

_DCFUNCT.PRG, DCLIPX.DLL


dc_msgbox()

Display an array of messages in a window

DC_MSGBOX() is used to display a set of message lines in a window. The two (2) starting coordinates and an array of characters strings are passed. The width and length of the box will be determined automatically by the width of the longest item and the number of items.

Syntax:

DC_MsgBox ( [<nStartRow>], ;
            [<nStartCol>], ;
            <aMessages>, ;
            [<cTitle>], ;
            [<lWait>], ;
            [<nSeconds>], ;
            [<lYesNo>], ;
            [@<nChoice>], ;
            [<aButtons>], ;
            [<aMenuId>], ;
            [<cMenuName>], ;
            [@<cHotKey>], ;
            [<cFont>], ;
            [<bEval>], ;
            [<nIcon>], ;
            [<lNoRestore>], ;
            [<lAlwaysOnTop>], ;
            [<aColor>], ;
            [<aButtonSize>, ;
            [<lHorizontal>], ;
            [<oOwner>] ) -> lStatus

Returns:

 A logical .TRUE. if the last key pressed by the user is a "Y",
 .FALSE. otherwise.

Arguments:

<nStartRow> is the starting screen row.
<nStartCol> is the starting screen column.
If no coordinates are given, then the message box will be
displayed in the middle of the screen.

<aMessages> is an array of character strings.

<cTitle> is the title to place at the top of the message box.
If this parameter is not passed, then the title will be the
default title established by DC_MsgBoxTitle().

<lWait> will add an additional line to the message box - "Press
any key to continue..." and wait for the user to press a key.

<nSeconds> will display the box for a specified number of
seconds or until a key is hit.

<lYesNo> if .t. will display YES / NO menu items below the
message text.  .F. (default) will behave normally.

<nChoice> : 1 will default to YES (default),  2 will default
to NO.  If passed by reference and an array of <aItems> is
also passed, then the value returned will be equivalent to
the menu item selected.

<aButtons> - An array of menu buttons to choose from.  The number
of the selected item will be returned in the <@nChoice>
variable.  This is a single dimensional array containing captions
for the buttons.

<aMenuId> - An optional array of unique Menu ID codes (up to 8
characters) for each menu item in <aButtons>.  This array is
needed to enable the PERSISTENT MENU SELECTION feature.  See
DC_MenuPull() for more information.

<cMenuName> - An optional parameter with a "unique" name for
this menu.  This name is needed to enable the PERSISTENT MENU
SELECTION feature.  See DC_MenuPull() for more information.

@<cHotKey> - An optional parameter to return the value of the
high-lighted letter in the selected menu item when using
DC_MSGBOX() with an array of menu items.  This must be a variable,
passed by reference, in which to store a character value.

<cFont> is the font to use for the message text.  This must conform
to standard font declarations used with the :setFontCompoundName()
method of XbpStatic().

<bEval> is a code block to evaluate after the Message box is
created.  The Messsage box dialog object is passed to the code
block.

<nIcon> is the icon to use in the message box text area.
The default is XBPSTATIC_SYSICON_ICONQUESTION when the YESNO clause
is used otherwise it is XBPSTATIC_SYSICON_ICONINFORMATION.

<lNoRestore> overrides the setting of DC_AutoRestoreWindow().

<lAlwaysOnTop> forces the window to remain on the top of all
other application windows.

<aColor> is a 2-element array of foreground and background colors.
The default color is set by the DC_MsgBoxColor() get-set function.

<aButtonWidth> is an array containing the width and height, in
pixels, of the buttons created with the <aItems> parameter,
otherwise the buttons will be sized to the longest caption.

<lHorizontal> will create the buttons horizontally instead of
vertically.

<oOwner> <oOwner> is the owner of the message box. If the owner
parameter is not used, the message box will center in the
object returned by the SetAppWindow() function, otherwise it
will center on the owner.

Notes:

If only one parameter, a Character string or an Array is passed, then DC_MSGBOX() will display the contents of the character string or the array and an "OK".

Examples:

 PROCEDURE Xtest( )

 LOCAL oOldAppWin := SetAppWindow(DC_QOUTWINDOW()), cFileName

 DC_Gui(.f.)

 DC_MSGBOX( 10,5, { 'You must open a data file first' },,.t. )

 SetAppWindow( oOldAppWin )

 DC_Gui( .t. )

 cFileName := 'JUNK'

 IF DC_MSGBOX( ,, { 'Delete '+cFileName+'? ' },  ;
                     'Delete a File',,,.t. )
   ERASE (cFileName)
 ENDIF

 RETURN

Files:

_DCMSG.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_alert()
   DCMSGBOX
   dc_msgboxtitle()
   dc_msgboxgui()
   dc_msgboxescape()


DC_MsgBoxColor()

A Get-set function to set the default color for DCMSGBOX.

DC_MsgBoxColor() is used to get or set the default color value for DC_MsgBox() and DCMSGBOX.

Syntax:

DC_MsgBoxColor( [<aColor>] -> <aOldColor>

Arguments:

<aColor> is a 2-element array containing a foreground color and a
background color.  Each element must be a numeric value or a 3-element
array containing the RGB values.

Examples:

DC_MsgBoxColor( { {255,0,0}, {255,255,255} } )

Files:

_dcmsg.prg, dclipx.dll

See Also:

   dc_msgbox()
   DCMSGBOX


dc_msgboxescape()

Set the behavior of the ESC key when using DC_MsgBox()

DC_MsgBoxEscape() is a Get/Set function that is used to set the behavior of the ESCAPE key when using DC_MsgBox() or DCMSGBOX.

Syntax:

DC_MsgBoxEscape( <lFalse> ) -> lOldValue

Returns:

A logical value.

Arguments:

<lFalse> if .TRUE. will cause DC_MsgBox() to return a .FALSE. if
the ESCAPE key is hit, otherwise it will return the value
associated with the default choice.

Files:

_dcmsg.prg

See Also:

   dc_msgbox()
   DCMSGBOX


dc_msgboxgui()

Force DC_MsgBox() to always display a GUI dialog

DC_MsgBoxGui(.t.) is used to force DC_MsgBox() to always display a GUI dialog even if the DC_Gui() flag is set to .FALSE.

Syntax:

DC_MsgBoxGui ( [<lGui>] ) - > lStatus

Returns:

 A logical .TRUE. if the last key pressed by the user is a "Y",
 .FALSE. otherwise.

Arguments:

<lGui> if .TRUE. will force all DC_MsgBox() dialogs to be
displayed as GUI.  If <lGui> is .FALSE. (default) then DC_MsgBox()
dialogs will be displayed in accordance with the DC_Gui()
function.

Notes:

If only one parameter, a Character string or an Array is passed, then DC_MSGBOX() will display the contents of the character string or the array and an "OK".

Files:

_DCMSG.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_msgbox()


dc_msgboxtitle()

Set the default title for DC_MsgBox()

DC_MsgBoxTitle() is used to establish a default title for message boxes created by DC_MsgBox() in the event that the <cTitle> parameter is not passed to DC_MsgBox().

Syntax:

DC_MsgBoxTitle ( [<cTitle>] ) -> cOldTitle

Returns:

 A character string.

Arguments:

<cTitle> is the title to place at the top of the message box.
If this parameter is NIL, then the name of the .EXE will be
placed in the title.

Examples:

 PROCEDURE Xtest( )

 LOCAL oOldAppWin := SetAppWindow(DC_QOUTWINDOW()), cFileName

 DC_MSGBOXTITLE('Attention!')
 DC_Gui(.f.)

 DC_MsgBox( 10,5, { 'You must open a data file first' },,.t. )

 SetAppWindow( oOldAppWin )

 DC_Gui( .t. )

 cFileName := 'JUNK'

 IF DC_MsgBox( ,, { 'Delete '+cFileName+'? ' },  ;
                     'Delete a File',,,.t. )
   ERASE (cFileName)
 ENDIF

 RETURN

Files:

_DCMSG.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_msgbox()
   DCMSGBOX


dc_num2bin()

Converts a Decimal number to a Binary String

DC_NUM2BIN() will convert a numeric value to a binary string.<br><br>

Syntax:

DC_Bin2Num( <nDecimal> ) -> cBinary

Returns:

 A Binary string from "00000000" to "11111111".

Arguments:

<nDecimal> is a numeric value from 0 to 255.

Files:

_DCAND.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_bin2num()
   dc_num2word()


dc_num2word()

Convert an integer number to a 2-byte word

DC_NUM2WORD() is used to convert an integer to a 2-byte word.<br><br><br><br>

Syntax:

 DC_Num2Word ( <nInteger> ) -> c2ByteWord

Returns:

 A 2-character string.

Arguments:

<nInteger> is any integer number.

Examples:

 The following example shows how to use DC_NUM2WORD() and
 DC_WORD2NUM() to save numeric values to a file and restore
 them.

 FUNCTION savenumbers ( aNumbers )

 // aNumbers := { 10, 45, 134, 678, 3, 200 }
 nHandle := fcreate( 'numbers.bin' )
 for i := 1 to len(aNumbers)
   fwrite( nHandle, DC_NUM2WORD( aNumbers[i] )
 next
 fclose( nHandle )
 return

 FUNCTION restnumbers

 local nHandle := fopen( 'numbers.bin' )
 local aNumbers := {}
 aadd( aNumbers, DC_WORD2NUM( freadstr( nHandle, 2 ) ) )
 fclose( nHandle )
 return aNumbers

Files:

_DCNUM.PRG, DCLIP2.DLL

See Also:

   dc_word2num()


dc_numincr()

Increment a numeric value within a string

DC_NUMINCR() is used to increment the last numeric portion of a string. This function is handy for incrementing serial numbers, coded strings, etc.<br><br>

Syntax:

 DC_NumIncr ( <cString>, ;
              [<cLoVal>], ;
              [<cHiVal>] ) -> cNewString

Returns:

 A string containing the new value.

Arguments:

<cString> is a character string.

<cLoVal> and <cHiVal> are optional parameters for setting a low
and high value.  If the number increments past <cHiVal> it will
automatically be set to <cLoVal>.

Examples:

 // print 100 serial number labels
 cSerial := 'DON-4567-A'
 set print on
 for i := 1 to 100
   ? '   '+cSerial
   ?
   ?
   cSerial := DC_NUMINCR( cSerial )
 next
 set print off

Files:

_DCNUM.PRG, DCLIP2.DLL


dc_object2js()

Convert an object to JSON

DC_Object2Js() converts an Xbase++ object to JSON (Javascript Object Notation). Only the iVars of the object will be included.

Syntax:

DC_Object2Js( <oObject> ) -> cJson

Returns:

A character string.

Arguments:

<oObject> is any Xbase++ object.

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_array2js()
   dc_array2xml()
   dc_object2xml()


dc_object2xml()

Convert an object to XML

DC_Object2Xml() is used to convert an Xbase++ object to an XML string.

Syntax:

DC_Object2Xml( <oObject> ) -> cXML

Returns:

A character string.

Arguments:

<oObject> is an Xbase++ object. Only iVars are included in the XML.

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_array2xml()
   dc_array2js()
   dc_object2js()


dc_objload()

Dynamically load an Xbase++ compiled .OBJ for execution

DC_OBJLOAD() is used to "dynamic-link" an Xbase++-compiled .OBJ file into memory for execution of any functions within the compiled .OBJ. This is done by creating a temporary .DLL with the same name as the .OBJ file and loading the .DLL. <br><br>

Syntax:

DC_ObjLoad ( <cObjName>, ;
             [<bcRunProc>] ) -> lStatus

Returns:

 A logical .TRUE. if the .OBJ file could be linked into a .DLL
 and the .DLL loaded for execution, .FALSE. otherwise.

Arguments:

<cObjName> is the name of the .OBJ file to link.  If no drive/
directory is included in the file name, then the .OBJ must
exist in the directory specified by the SET ODIR command, ODIR=
in DCLIP.SYS, or DC_SETT('ODIR',<path>).

If a <bcRunProc> argument is passed, the <bcRunProc> procedure or
function will be automatically executed.  This may be the name
of a procedure or function in quotes or a code block.

Examples:

 -- Example 1 --

 do while .t.
   @ 10,10 prompt "Calculator"
   @ 11,10 prompt "Calendar"
   @ 12,10 prompt "Note Book"
   menu to nChoice
   do case
     case nChoice = 1
       DC_OBJLOAD( "calc", "pop_calc(.t.)" )
     case nChoice = 2
       DC_OBJLOAD( "calendar", "time_chart()" )
     case nChoice = 3
       DC_OBJLOAD( "notebook", "notebook()" )
   endcase
 enddo

 -- Example 2 --

 accept "enter a function to execute" to cFunction
 cObjName := dc_objfind( cFunction )
 DC_OBJLOAD( cObjName )
 dc_do( cFunction )

Files:

_DCLINK.PRG

See Also:

   dc_compile()


dc_objpublic()

List .OBJ(s) that contain public function

DC_ObjPublic() is used to scan a set of .OBJ files and list the names of all .OBJs that contain a PUBLIC declaration of a specified function.<br><br> A file named DCPUBLIC.TXT will be created using the Xbase++ XPPFILT.EXE utility program. This file will contain a listing of all public functions in all .OBJs.

Syntax:

 DC_ObjPublic( [<cProc>], ;
               [<lDisplayWindow>], ;
               [<lListAll>] ) -> acObjName

Returns:

 A single dimensional array containing the names of all the
 .OBJs that contain the function/procedure.

Arguments:

<cProc> is the name of the procedure/function to find.
If this argument is empty, a GUI dialog will be displayed to
prompt the user for a procedure name.

<lDisplayWindow> if .TRUE. (default) will display a window
with the results.

<lListAll> if .TRUE. (default) will list all occurrences.

Notes:

All .OBJs in the search directory(s) established by the SET ODIR (eXPress++) environment variable. If this environment variable is empty, then the search path is established by the operating system SET OBJ environment variable.

Examples:

 . aProcs := DC_ObjPublic('MAIN')
 . ? aProcs
{ TEST.OBJ, TEST2.OBJ, JUNK.OBJ }

Files:

_DCOFIND.PRG, DCLIP2.DLL

See Also:

   dc_objsource()


dc_objsource()

Get the source code name from an .OBJ file

DC_ObjSource() is used to extract the full path name of the original source code from an .OBJ file.

Syntax:

 DC_ObjSource( <cObjFile> ) -> cSourceFile

Returns:

 A character string.

Arguments:

<cObjFile> is the name of the XPP-Compiled .OBJ file.

Notes:

This function assumes that the source file has the same name as the obj file except with the .PRG extension. This function is needed when it is not known which directory the source resides.

Examples:

 . ? DC_ObjSource('C:\OBJS\BROWSE.OBJ')
C:\SOURCE\BROWSE.PRG

Files:

_DCOFIND.PRG, DCLIP2.DLL

See Also:

   WHERE SOURCE
   dc_objpublic()


dc_objsourcelist()

Display a list of .OBJ/.PRG files containing PUBLIC proc

DC_ObjSourceList() is used to display a list of .OBJ files and the location of the original source that contain a specified PUBLIC procedure.

Syntax:

 DC_ObjSourceList( <cProc> ) -> lStatus

Returns:

 A logical .TRUE. if a list was displayed, .FALSE. otherwise.

Arguments:

<cProc> is the name of the PUBLIC procedure to find.

Notes:

This function assumes that the source file has the same name as the obj file except with the .PRG extension. This function is needed when it is not known which directory the source resides.

Examples:

 . DC_ObjSourceList('main')

Files:

_DCOFIND.PRG, DCLIP2.DLL

See Also:

   WHERE SOURCE
   dc_objsource()


dc_odblock()

Get a Progress indicator code block to pass to dbeval()

DC_ODBLOCK() returns a code-block that is a substitute for the WHILE condition code block that is used with database functions such as DBEVAL().<br><br> Use DC_ODBLOCK() to install a progress odometer to your database operations that perform tasks on multiple records, such as indexing, deleting, copying, recalling, etc.<br><br> The code block returned by DC_ODBLOCK() uses the DC_ODOMETER() function to display the progress indicator. This odometer also checks the keyboard after each record and will abort the operation if the ESCape key is pressed.

Syntax:

DC_OdBlock ( [<bWhileCondition>], ;
             [<bForCondition>], ;
             [<nNext>], ;
             [<nStep>], ;
             [<cMessage>], ;
             [<lForExit>], ;
             [<lWait>], ;
             [<nRecords>], ;
             [<lRest>], ;
             [<cTitle>] ) -> bProgress

Returns:

 A code block that usess the DC_ODOMETER() function.

Arguments:

<bWhileCondition> is the same code block that would be passed
to dbeval() as the WHILE condition.

<bForCondition> is a code block which will be evaluated for
each record.  If the code block evaluates .TRUE. then the tally
count in the progress indicator will be incremented by 1.

<nNext> is the number of records.

<nStep> is an optional parameter which is used to specify how
often the odometer function will be called.  <nStep> is a
numeric value representing the number of records that will be
processed before the odometer function will be called.
Increasing the <nStep> number will improve speed performance,
however the progress indicator resolution will be lowered.

<cMessage> is the the message to be displayed in the progress
box. For example, if you are deleting records, then the message
may be "deleted", or if you are copying records the message may
be "copied".

<lForExit> if .TRUE. will display the progress indicator until
the <bForCondition> evaluates .TRUE.  Use this option when
performing an operation such as a LOCATE, where the FOR
condition terminates the operation as soon as it evaluates
.TRUE.

<lWait> if .TRUE. will leave the odometer status on the screen
after all records are evaluated until a key is pressed.
Default is .FALSE.

<nRecords> is used only when working with an index that contains
a subset of the total records in the database.  An example would
be using a filter on the database, a conditional index, or
features like SCOPETOP and SCOPEBOTTOM.  If your RDD supports
a function that returns the amount of keys in the index then
use this value, otherwise you may need to calculate the value.
If no argument is given or the value of <nRecords> doesn't
exactly match the number of valid records in the database then
the progress indicator may not be accurate when reporting
percentage.

<lRest> should be the same value as the <lRest> parameter in
your DBEVAL() function that uses DC_ODBLOCK().

<cTitle> is the title you wish to appear at the top of the
progress window.

Examples:

 lOdometer := .t.
 cFor := space(40)
 @ 10,10 say "Enter FOR condition " get cFor
 @ 11,10 say "Do you want a progress odometer? " get lOdometer
 bFor := {||&cFor}
 if lOdometer
   bWhile := DC_ODBLOCK( ,bFor,,,"Deleted",,.t.,,,;
             'Deleting Records' )
 else
   bWhile := { || .t. }
 endif
 dbeval( { || dbDelete() }, bFor, bWhile )

Files:

_DCODD.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_odometer()
   dc_progress()
   dc_working()


dc_odometer()

Display a progress indicator for database/index operations

DC_ODOMETER() displays a progress indicator odometer for database operations that perform tasks on multiple records, such as indexing, deleting, copying, recalling, etc.<br><br> The code block returned by DC_ODBLOCK() uses the DC_ODOMETER() function to display the progress indicator. This odometer also checks the keyboard after each record and will abort the operation if the ESCape key is pressed.

Syntax:

DC_Odometer ( <bForCondition>, ;
              <nStep>, ;
              <cMessage>, ;
              <lForExit>, ;
              <lWait> ) -> lStatus

Returns:

 A logical .T. until the end-of-file is reached or until the
 ESCape key is pressed.

Arguments:

<bForCondition> is a code block which will be evaluated for
each record.  If the code block evaluates .TRUE. then the tally
count in the progress indicator will be incremented by 1.

<nStep> is an optional parameter which is used to specify how
often the odometer function will be called.  <nStep> is a
numeric value representing the number of records that will be
processed before the odometer function will be called.
Increasing the <nStep> number will improve speed performance,
however the progress indicator resolution will be lowered.

<cMessage> is the the message to be displayed in the progress
box. For example, if you are deleting records, then the message
may be "deleted", or if you are copying records the message may
be "copied".

<lForExit> if .TRUE. will display the progress indicator until
the <bForCondition> evaluates .TRUE.  Use this option when
performing an operation such as a LOCATE, where the FOR
condition terminates the operation as soon as it evaluates
.TRUE.

<lWait> if .TRUE. will leave the odometer status on the screen
after all records are evaluated until a key is pressed.
Default is .FALSE.

Notes:

Use DC_ODACTIVE(.t.) before calling your database function that invokes DC_ODOMETER() followed by DC_ODACTIVE(.f.) when the operation is completed.

DC_ODOMETER() requires that a value for all parameters is passed, no NIL arguments allowed. Parameter validation is not included in this function to improve speed.

Examples:

 lOdometer := .t.
 cFor := space(40)
 @ 10,10 say "Enter FOR condition " get cFor
 @ 11,10 say "Do you want a progress odometer? " get lOdometer
 bFor := {||&cFor}
 if lOdometer
   bWhile := { || DC_ODOMETER( bFor,1,"Deleted",.f.,.t. ) }
 else
   bWhile := { || .t. }
 endif
 dbeval( { || dbDelete() }, bFor, bWhile )

Files:

_DCODD.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_odpercent()
   dc_odblock()
   dc_progress()
   dc_working()


dc_odpercent()

Set numeric value for progress indicator percentage of update

DC_ODPERCENT() sets how often to update the progress indicator odometer when using DC_ODOMETER() or DC_ODBLOCK().

Syntax:

DC_OdPercent ( <nPercent> ) -> nil

Arguments:

<nPercent> is a numeric value for the percentage of update
you want on the progress odometer.  If you have very large
files and want to see progress more often, then it is
recommended you lower this number from the default of 5
percent.

Examples:

 DC_ODPERCENT( 1 )  // 1 percent
 index on cust_nmbr to custnmbr

Files:

_DCODD.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_odometer()
   dc_odblock()


dc_openindex()

Open a set of index files

DC_OPENINDEX() is used to open a set of index files. It allows for designing of an application that is easily configurable to any database driver by simply setting the DBE before starting the application. If index files are opened via DC_OPENINDEX(), they will be created if they don't already exist using the current DBE.<br><br>

Syntax:

DC_OpenIndex ( [<cDirectory>], ;
               [<cCombName>], ;
               <aTagInfo>, ;
               [<lCombined>], ;
               [<lCreate>], ;
               [<lNoProgress>], ;
               [<cTitle>] ) -> lStatus

Returns:

 A logical .TRUE. if the index(es) were opened successfully,
 .FALSE. otherwise.

Arguments:

<cDirectory> is the directory to search for the index.  If no
parameter is passed then the current SET_DEFAULT followed by
SET_PATH will be searched.

<cCombName> is the name of a "combined index" file name to
create if <lCombined> is .TRUE. and if the current DBE supports
combined indexes. If the current DBE does not support combined
indexes, then these parameters are ignored.

<aTagInfo> is a multi-dimensional array containing the
information about each index to open (or create if it does not
exist).  Each sub-array consists of 6 elements:

Element   Type   Description
-------   ----   ----------------------------------------------
  [1]      C     FileName of Index (ignored if combined index)
  [2]      C     Tag Name
  [3]      C     Index Key expression
  [4]      C     "For" condition expression
  [5]      L     .True. if index is UNIQUE, .False. otherwise
  [6]      L     .True. if index is DESCENDING, .False.
                 otherwise
  [7]      C     Description of this index

<lCombined> if .TRUE. designates that the index is a combined
index containing multiple tags.

<lCreate> if .TRUE. will re-create the indexes even if they
already exist.  If .FALSE. (default) then the indexes will
be created only if they don't exist.

<lNoProgress> if .TRUE. will not display the progress bar
while indexing.  If .FALSE. (default) then a progress bar
is displayed showing the percentage of progress during the
index creation.  Some data drivers (i.e. DBFNTX) create
larger index files when a progress bar is displayed
via the EVAL option.  The progress bar may also slow the
indexing by approximately 20%.

<cTitle> is the title of the progress bar dialog window.

Examples:

 // In this example, if the DBFNTX driver is active then three
 // index files named DCHELP1.NTX, DCHELP2.NTX and DCHELP3.NTX
 // will be created.  If the DBFCDX driver is active then 1
 // combined index named DCHELP.CDX will be created with 3
 // tags: COMMAND, SORT and CATEGORY. In either case,
 // SET ORDER TO 1,2 or 3 will select the same index.

 DC_OPENINDEX( , 'DCHELP',;
       {{ 'DCHELP1','COMMAND','COMMAND',,.t. }, ;
        { 'DCHELP2','SORT','SORT+COMMAND'},     ;
        { 'DCHELP3','CATEGORY','CATEGORY+COMMAND'} }, .t. )

Files:

_DCDBIND.PRG, DCLIP1.DLL

See Also:

   dc_dbfile()
   dc_usearea()


dc_pack()

Pack the current database

DC_PACK() is a high-level function that will pack the database in the currently selected work area. This function does not use the Clipper dbPack() function but instead packs the file as follows:<br><br> 1. Displays a progress odometer during the packing process. 2. Optimizes size of memo fields (removes dead space). 3. Creates a backup file.<br><br>

Syntax:

 DC_Pack ( [<lUserPrompt>], ;
           [<cPackMethod>] ) -> lStatus

Returns:

 A logical .TRUE. if the database was successfully packed,
 .FALSE. otherwise.

Arguments:

<lUserPrompt> if .TRUE. will prompt the user to continue or
abort the packing process, if .FALSE. the pack will be
performed with no user input.

<cPackMethod> is a single character designating the type
of pack to perform.

 cPackMethod
 -----------
 "F" - Fast (default)
 "S" - Slow (removes dead-space from memo file)

Examples:

 do while .t.
   @ 10,10 prompt "open a database"
   @ 11,10 prompt "browse database"
   @ 12,10 prompt "pack database"
   menu to nChoice
   do case
     case nChoice = 1
       dc_dbfopen()
     case nChoice = 2
       dc_browsedb()
     case nChoice = 3
       DC_PACK()
   endcase
 enddo

Files:

_DCDBPK.PRG, DCLIP1.DLL

See Also:


dc_parent()

Get the Alias name of the Parent database

DC_PARENT() is used to determine the alias name of a database that is that has a parent to child relationship to the currently selected database.<br><br> If there is no parent to child relationship, a null string will be returned.<br><br>

Syntax:

 DC_Parent ( [<lSelect>] ) -> cAlias

Returns:

 A character string.

Arguments:

<lSelect> if .TRUE. will also select the parent database's
work area.  .FALSE. is the default.

Examples:

 . USE invoices INDEX invcust
 . USE customer NEW
 . SET RELATION TO cust_nmbr INTO invoice
 . SELECT invoice
 . ? DC_PARENT()
 CUSTOMER

Files:

_DCPAREN.PRG

See Also:

   dc_parentval()


dc_parentval()

Get the Alias name of the Parent database

DC_PARENTVAL() is used to get the value of the parent to child relational data that is being used to make the relation.<br><br><br><br>

Syntax:

 DC_ParentVal ( [@<cParentName>], ;
                [@<cRelExpr>] ) -> xValue

Returns:

 A value equivalent to the relational expression based on the
 currently selected record of the Parent Database.

Arguments:

@<cParentName> is the name of a variable to store the name of
the parent alias.

@<cRelExpr> is the name of a varialbe to store the relational
expression.

Examples:

 . USE invoices INDEX invcust
 . USE customer NEW
 . SET RELATION TO cust_nmbr INTO invoice
 . SKIP 10

 . ? cust_nmbr
 23876

 . SELECT invoice

 . ? DC_PARENTVAL()
 23876

Files:

_DCPAREN.PRG

See Also:

   dc_parent()


dc_path()

Return the path or file name from a file specification string

DC_PATH() is used to extract only the drive and directory name or the file name from a string that contains both.

Syntax:

DC_Path ( <cFileSpec>, ;
          [<lFileName>] ) -> cPath / cFileName

Returns:

 A character string.

Arguments:

<cFileSpec> is a string containing a directory and file name.

<lFileName> if .False. (default) will return the path from the
string.  If .True. then the file name will be returned.

Examples:

 set default to g:\customer\data
 use customer
 cFileSpec := dc_dbfname()
 ? cFileSpec
  G:\CUSTOMER\DATA\CUSTOMER.DBF
 ? DC_PATH(cFileSpec)
  G:\CUSTOMER\DATA\
 ? DC_PATH(cFileSpec,.t.)
  CUSTOMER.DBF

Files:

_DCPATH.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_ispath()
   dc_pathfound()


dc_pathfound()

Return the directory name in which a file is found

DC_PATHFOUND() will search the directory designated as the SET DEFAULT directory, then all the directories in the SET PATH directory path to see if a file exists and return the first directory name in which the file is found. This function is a companion to the FILE(), FOPEN(), DBUSEAREA(), DBSETINDEX() functions or any other functions in which the directories are searched in the above order. This function is handy when it is necessary to know in which directory a file is found.

Syntax:

DC_PathFound ( <cFileName> ) -> cDirectory

Returns:

 A character string.

Arguments:

<cFileName> is the name of the file to find.

Examples:

 SET DEFAULT TO \customer\data
 SET PATH TO \mytools;\dclip
 ? DC_PATHFOUND('CUSTOMER.DBF')
 \customer\data\
 ? DC_PATHFOUND('MYTOOLS.DBF')
 \mytools\
 ? DC_PATHFOUND('DCPRINT.DBF')
 \dclip

Files:

_DCPATH.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_path()


dc_pause()

Pause program execution for a specified amount of time

DC_PAUSE() is used add a delay to the program by using the SECONDS() function in a loop. The processor will continue to service all other threads during the pause.<br><br>

Syntax:

DC_Pause ( <nSeconds>, ;
           <lAbort> ) -> nil

Returns:

 nil

Arguments:

<nSeconds> is the amount of time to pause.

<lAbort> if .TRUE. will abort the pause if any key is
pressed or if a mouse button is pressed.  If .FALSE.
(default), then the pause will continue regardless of
the keyboard or mouse activity.

Examples:

PROCEDURE Xtest( )

LOCAL nStartTime, nEndTime, cScrn

DC_Gui(.t.)

cScrn := DC_WaitOn()

nStartTime := Seconds()

DC_PAUSE( 2.5 )  // Pause 2.5 seconds

nEndTime := Seconds()

DC_Impl(cScrn)

DC_MsgBox('Elapsed time is ' + Str(nEndTime-nStartTime))

RETURN

Files:

_DCPAUSE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_wait()


dc_pickcase()

A function that replaces CASE..ENDCASE statements

DC_PICKCASE() is a handy function that can be used as a replacement for DO CASE.. CASE.. ENDCASE statements in your code. Sometimes it is necessary to replace a set of commands with a simple function.<br><br> For example this code:<br><br> nInkey := INKEY(0) DO CASE CASE nInkey = K_ALT_A bBlock := {||AddRecord()} CASE nInkey = K_ALT_B bBlock := {||DelRecord()} CASE nInkey = K_ALT_E bBlock := {||EditRecord()} ENDCASE Eval(bBlock)<br><br> can be replaced by this code:<br><br> nInkey := INKEY(0) bBlock := ; DC_PICKCASE( nInkey, '=', { K_ALT_A, K_ALT_B, K_ALT_E },; { {||AddRecord()}, {||DelRecord()}, {||EditRecord()} } ) Eval(bBlock)<br><br>

Syntax:

DC_PickCase ( <xValue>, ;
              <cOperator>, ;
              <aValues>, ;
              <aReturn> ) -> xValue

Returns:

 An element from <aReturns>.

Arguments:

<xValue> is any value of the same TYPE as the values in
<aValues>.  For example, if <aValues> is a set of character
strings, then <xValue> must be a character string.

<cOperator> is the operator to use when performing the CASE
evaluation.  Only the following operators are valid:

Operator    Description
--------   --------------------------
  =         Equal to
  ==        Exactly equal to
  >         Greater than
  <         Less than
  >=        Greater than or Equal to
  <=        Less than or Equal to
  <>        Not Equal to
  $         Contains

<aValues> is an array of values to match to <xValue> based
on <cOperator>.  The position in the array (element number) of
the first CASE that matches will become a pointer the the
value in <aReturns> to return.

<aReturn> is an array of the same length as <aValues>.  This
array may contain data elements of any type.

Examples:

aArray1 := { 1000000, 100000, 10000, 1000, 100, 10 }
aArray2 := {       1,      2,     3,    4,   5,  6 }

? DC_PICKCASE( 500000, '>=', aArray1, aArray2 )
2

Files:

_DCEVAL.PRG/.OBJ, DCLIPX.LIB


dc_pointerarrow()

Set the mouse pointer to an arrow

DC_POINTERARROW() is used to change the mouse pointer to an an arrow for all objects in an object tree. This function walks down the :ChildList() tree and sets the mouse pointer on all children of the specified object.<br><br> Use this function to set a the pointer to an arrow after previously setting it to an hourglass style pointer when performing operations that create a busy state.<br><br>

Syntax:

 DC_SetPointerArrow ( <oXbp> ) -> nil

Returns:

 Nil.

Arguments:

<oXbp> is the parent object.  For example, to insure that the
mouse pointer will be changed for all child objects in the current
application window, <oXbp> would be SetAppWindow().

Examples:

#include "dcdialog.ch"
#include "dccursor.ch"

PROCEDURE Xtest()

LOCAL GetList := {}, oDlg, GetOptions

@ 1,1 DCSAY "Please wait while packing file..."  SAYSIZE 40,2 ;
   FONT 'Helv.24.Bold'

DCGETOPTIONS ;
   NOMINBUTTON ;
   NOMAXBUTTON

DCREAD GUI FIT EXIT OPTIONS GetOptions PARENT @oDlg

DC_PointerWait( oDlg )

DC_Pause(5)

DC_PointerArrow( oDlg )

oDlg:Destroy()

RETURN

Files:

_DCMOUSE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_setpointertree()
   dc_pointerwait()


dc_pointerwait()

Set the mouse pointer to an hourglass

DC_POINTERWAIT() is used to change the mouse pointer to an hourglass (wait) for all objects in an object tree. This function walks down the :ChildList() tree and sets the mouse pointer on all children of the specified object.<br><br> Use this function to set an hourglass style pointer when performing operations that create a busy state.<br><br>

Syntax:

 DC_SetPointerTree ( <oXbp> ) -> nil

Returns:

 Nil.

Arguments:

<oXbp> is the parent object.  For example, to insure that the
mouse pointer will be changed for all child objects in the current
application window, <oXbp> would be SetAppWindow().

Examples:

#include "dcdialog.ch"
#include "dccursor.ch"

PROCEDURE Xtest()

LOCAL GetList := {}, oDlg, GetOptions

@ 1,1 DCSAY "Please wait while packing file..."  SAYSIZE 40,2 ;
   FONT 'Helv.24.Bold'

DCGETOPTIONS ;
   NOMINBUTTON ;
   NOMAXBUTTON

DCREAD GUI FIT EXIT OPTIONS GetOptions PARENT @oDlg

DC_PointerWait( oDlg )

DC_Pause(5)

oDlg:Destroy()

RETURN

Files:

_DCMOUSE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_setpointertree()
   dc_pointerarrow()


dc_popcalc()

A popup, full-function calculator

DC_POPCALC() is a calculator that can be called from Xbase++ code or in a code-block via the POPUP clause in the DCSAY..GET command. This is a Dual-Mode function that is displayed as a TEXT-mode calculator when TEXT mode is invoked via DC_GUI(.f.) or as a GUI-mode calculator when GUI mode is invoked via DC_GUI(.t.)

Syntax:

 DC_PopCalc( [<nValue>], ;
             [<nStRow>], ;
             [<nStCol>], ;
             [<cTitle>],;
             [<@lOK>], ;
             [<lModal>], ;
             [<bHelp>], ;
             [<lInteger>]) -> nValue

Returns:

 The value of the calculator accumulator (numeric).

Arguments:

<nValue> is the starting value to place in the accumulator.
If no value is passed then the STATIC value stored in memory
will be the default.

<nStRow> and <nStCol> are the start display coordinates.  If
no values are passed then the calendar will be displayed
relative to the current cursor position (in TEXT mode)
or in the center of the screen (in GUI mode).  These coordinates
are text-based coordinates based on a home position of 0,0.
In GUI mode they are automatically converted to GUI-based
coordinates.

@<lOk> is a logical variable, passed by reference.  If the user
exits with an ABORT or ESCAPE, the variable will contain a
.FALSE., otherwise it will contain a .TRUE.

<cTitle> is the title in the titlebar area of the calculator.

<lModal> if .TRUE. (default) will make the dialog window modal,
otherwise it will be modeless.

<bHelp> is a code block that is evaluated when the user presses
the F1 key or clicks on the HELP button.

<lInteger> if .TRUE. will display the calculator accumulator without
decimals.

Examples:

 #include "dcdialog.ch"

 FUNCTION XTest()

 LOCAL GetList := {}, nNumber := 1234.56, oMsgBox

 DC_GUI(.t.)

 @ 1,1 DCSAY 'Enter Number' GET nNumber ;
  POPUP {|n|DC_PopCalc(n)} ;
  MESSAGE 'Click on arrow for a calculator' ;
  INTO oMsgBox

 @ 3,1 DCMESSAGEBOX OBJECT oMsgBox SIZE 30

 DCREAD GUI FIT ADDBUTTONS

 RETURN nil

Files:

_DCCALC.PRG/.OBJ, DCLIPX.DLL

See Also:

   dc_guipopcalc()


dc_popcolor()

A pop-up dialog for selecting Colors

DC_POPCOLOR() is a Color Choosing Dialog that can be called from Xbase++ code or in a code-block via the POPUP clause in the DCSAY..GET command. <br><br>

Syntax:

 DC_PopColor( [<acColor>], ;
              [<nMode>], ;
              [<lRGB>], ;
              [<cTitle>], ;
              [<lSafe>], ;
              [<lModal>], ;
              [<oParent>] ) -> acColor

Returns:

An array of numeric values.

Arguments:

<acColor> is the default color or code block to return if the
operator aborts the dialog.

<nMode> is used to select a dialog mode and the type of value
to return.

If <nMode> is 0, then DC_PopColor() is used to choose a
foreground and background color and return the choice as an
array of two numeric values.

If <nMode> is 1, then DC_PopColor() is used to choose a
foreground and background color and return the choice as a
character string in the form of a code block that can be macro
compiled and evaluated to return the 2-element array.  This is
handy for data-driven applications where the color must be stored
as a string.

If <nMode> is 2, then DC_PopColor() is used to choose a single
color and return the choice as a numeric value.

<lRGB> if .TRUE. will popup a color palette of RGB colors and
return the values as a RGB color.  The default is .FALSE.

<cTitle> is the title of the color dialog window.

<lSafe> if .TRUE. will present only 216 colors to choose from.
This is the color-safe palette used in Web applications and
Citrix / Terminal Server clients that choose only 256 colors.
Default is .FALSE. (16 million colors).

<lModal> if .TRUE. makes the dialog modal.  Default is .FALSE.

<oParent> is the parent of the window.  Default is AppDeskTop().
Note: do not pass a parent if using the <lModal> clause.

Examples:

 #include "dcdialog.ch"

 FUNCTION XTest()

 LOCAL GetList := {}, cColor := Space(50), oMsgBox

 @ 1,1 DCSAY 'Enter a Color Code Block' GET cColor ;
  POPUP {|c|DC_PopColor(c,0,.f.)} ;
  MESSAGE 'Click on arrow for a Color Picker' ;
  INTO oMsgBox

 @ 3,1 DCMESSAGEBOX OBJECT oMsgBox SIZE 30

 DCREAD GUI FIT ADDBUTTONS

 RETURN cColor

Files:

_DCCOLOR.PRG/.OBJ, DCLIPX.DLL

See Also:

   dc_presedit()


dc_popdate()

A pop-up calendar for selecting a date

DC_POPDATE() is a calendar that can be called from Xbase++ code or in a code-block via the POPUP clause in the DCSAY..GET command. This is a Dual-Mode function that is displayed as a TEXT-mode calendar when TEXT mode is invoked via DC_GUI(.f.) or as a GUI-mode calendar when GUI mode is invoked via DC_GUI(.t.).<br><br>

Syntax:

 DC_PopDate( [<dCurDate>],;
             [<nStRow>], ;
             [<nStCol>], ;
             [@<lOk>], ;
             [<cTitle>], ;
             [<lModal>], ;
             [<nStyle>], ;
             [<bHelp>], ;
             [<lHide>], ;
             [<lInstall>], ;
             [@<oDialog>], ;
             [@<aGetList>], ;
             [<bIsHoliday>], ;
             [<aColors>] ) -> dDate

Returns:

 The date selected.

Arguments:

<dCurDate> is the starting date to highlight in the calendar.
If no value is passed then the current system date will be
the default.

<nStRow> and <nStCol> are the start display coordinates.  If
no values are passed then the calendar will be displayed
relative to the current cursor position (in TEXT mode)
or in the center of the screen (in GUI mode).  These coordinates
are text-based coordinates based on a home position of 0,0.
In GUI mode they are automatically converted to GUI-based
coordinates.

@<lOk> is a logical variable (passed by reference).  This variable
will receive a .TRUE. if the user clicks on OK, double-clicks
on a date. or presses ENTER.  It will receive a .FALSE. if the
use clicks on ABORT or presses ESCape.

<cTitle> is the title in the Dialog Window.

<lModal> if .TRUE. (default) will make the dialog window modal,
otherwise it will be modeless.

<nStyle> is used to determine the style of the popup calendar.
This parameter is ignored in non-GUI mode.

  <nStyle>      Description
  ---------    ------------------------------------------------
      1         Large Calendar (original version)
      2         Small Calendar (with fancy buttons)
      3         Reserved.
      4         Small Calendar (without fancy buttons)

<bHelp> is a code block that is evaluated when the user presses
the F1 key.

If <lHide> is .TRUE., the calendar dialog is not destroyed when
exited. Instead it is hidden until DC_PopDate() is called again.
This provides the benefit of displaying the calendar instantly
after the first call to DC_PopDate().  The small calendar takes
longer to create because there are many more objects required
to handle the fancy buttons.  The default is .FALSE.

<lInstall> is used only with the <lHide> parameter.  It should
be passed as .TRUE. and used only once at the beginning of the
program in the main thread.  It installs the calendar as a
hidden calendar under the main thread to prevent lockups caused
by creating the hidden calendar in a different thread that is
later terminated.

@<oDialog> is a variable, passed by reference, to store a pointer
to the dialog window created by DC_PopDate().  This variable is
ignored if <nStyle> is 1 or <lHide> is .FALSE.

@<aGetList> is a variable, passed by reference, to store a
pointer to to GetList array used to create the calendar dialog.
This variable is ignored if <nStyle> is 1 or <lHide> is .FALSE.

<bIsHoliday> is a code block to evaluate to determine if a date
is a holiday.  This code block is called before painting each
date on the calendar.  The date is passed to the code block and
the code block must return a logical .T. if the date is a holiday
or a .F. if it is not a holiday.  Dates which are holidays are
displayed in the "holiday" color defined in the <aColors> array.
NOTE: this feature is available only in the "small calendar" -
style 2.

<aColors> is an array of 4 colors. Each element of the array is
a 2-element array containing a foreground and a background color
for the four different calendar colors.  See the below table.

Array Element     Description
-------------     -------------------------------------------
  [1]             Normal Color
  [2]             Today Color (Today's date)
  [3]             Passed-In Date Color
  [4]             Holiday Color

Example:

aColors := { ;
  { GRA_CLR_BLACK, GRA_CLR_WHITE }, ; // normal color
  { GRA_CLR_BLUE, GRA_CLR_WHITE }, ;  // today color
  { GRA_CLR_RED, GRA_CLR_WHITE }, ;   // passed date color
  { GRA_CLR_GREEN, GRA_CLR_WHITE }, ; // holiday color
}

Examples:

#include "dcdialog.ch"

FUNCTION XTest()

LOCAL GetList := {}, dDate := Date(), oMsgBox

DC_GUI(.t.)

@ 1,1 DCSAY 'Enter Date' GET dDate ;
  POPUP {|d|DC_PopDate(d,,,,,,3)} ;
  MESSAGE 'Click on arrow for a calendar' ;
  INTO oMsgBox

@ 3,1 DCMESSAGEBOX OBJECT oMsgBox SIZE 30

DCREAD GUI FIT ADDBUTTONS

RETURN nil

 * ------------ Display Holidays ------------- *

FUNCTION XTest2()

LOCAL dDate := Date()+2, cTitle, lModal, bIsHoliday, nStyle, aColors

cTitle := 'Pick a Holiday'
bIsHoliday := {|d,x|x:=Dow(d)==1,x}
lModal := .T.
nStyle := 2

aColors := { ;
  { GRA_CLR_BLACK, GRA_CLR_WHITE }, ; // normal color
  { GRA_CLR_BLUE, GRA_CLR_WHITE }, ;  // today color
  { GRA_CLR_RED, GRA_CLR_WHITE }, ;   // passed date color
  { GRA_CLR_GREEN, GRA_CLR_WHITE }, ;           // holiday color
}

DC_PopDate( dDate,,,,cTitle,lModal,nStyle,,,,,, ;
            bIsHoliday, aColors )

RETURN nil

Files:

_DCCALEN.PRG/.OBJ, DCLIPX.DLL

See Also:

   dc_guipopdate()


dc_popdatestart()

Select Monday or Sunday as start of week

DC_POPDATESTART() is used to set Sunday or Monday as the start of the week when displaying the calendar with DC_POPDATE() or DC_GUIPOPDATE().<br><br>

Syntax:

 DC_PopDateStart( [<lMonday>] )

Returns:

 The previous setting (a logical value).

Arguments:

<lMonday> if .TRUE. will set the start of the week as Monday.
If .FALSE. (default), the start of the week will be Sunday.

Files:

_DCCALEN.PRG/.OBJ, DCLIPX.DLL

See Also:

   dc_guipopdate()
   dc_popdate()


dc_popdateweek()

Set the suffix to use when displaying the calendar week

DC_PopDateWeek() is used to enable the display of the manufacturing week in the calendar.<br><br><br><br>

Syntax:

 DC_PopDateWeek( [<cSuffix>] ) -> cOldSuffix

Returns:

A Character string.

Arguments:

<cSuffix> is the suffix to display.  If no week number is to be
displayed then use "".

Examples:

DC_PopDateWeek('Wk') will display the week number with the
suffix "Wk".

Files:

_DCCALEN.PRG/.OBJ, DCLIPX.DLL

See Also:

   dc_guipopdate()
   dc_popdate()


dc_popdir()

A dialog for choosing a directory

DC_POPDIR() is a directory picker that can be called from Xbase++ code or in a code-block via the POPUP clause in the DCSAY..GET command.

Syntax:

 DC_PopDir ([<cDirectory>], ;
            [<cAvailDrives>], ;
            [<cExcludeDrives>], ;
            [<cWildCard>] ) -> cDirectory

Returns:

When the file dialog is closed with the "OK" pushbutton, this
function returns the selected directory.  If it is closed with
the "CANCEL" button, then the passed directory is returned.

Arguments:

<cDirectory> is the name of the default directory.  If this
argument is not passed, then the current directory is default.

<cAvailDrives> is a character string containing the letters of
all drives which are available for browsing.  For example the
string "CDEHIJK" will allow only these drives to be accessed.
The default is all mapped drives.

<cExcludeDrives> is a character string containing the letters of
all drives which are excluded from browsing.  For example the
string "AB" will prevent the floppy drives (A and B) from
being accessed.  The default is no excluded drives.

<cWildCard> is a wildcard template for files to include in the
files panel.

Examples:

 #include "dcdialog.ch"

 FUNCTION XTest()

 LOCAL GetList := {}, cDirectory := Space(60), oMsgBox

 DC_GUI(.t.)

 @ 1,1 DCSAY 'Enter Directory' GET cDirectory ;
  POPUP {|c|DC_PopDir(c)} ;
  MESSAGE 'Click on button for directory picker dialog' ;
  INTO oMsgBox

 @ 3,1 DCMESSAGEBOX OBJECT oMsgBox SIZE 30

 DCREAD GUI FIT ADDBUTTONS

 RETURN nil

Files:

_DCFUNCT.PRG/.OBJ, DCLIPX.DLL

See Also:

   dc_popfile()
   @ DCDIRTREE


dc_popfile()

A dialog for choosing a file

DC_POPFILE() is a file picker that can be called from Xbase++ code or in a code-block via the POPUP clause in the DCSAY..GET command.

Syntax:

 DC_PopFile([<cFileName>], ;
            [<cDirectory>], ;
            [<cWildCard>]. ;
            [<cTitle>], ;
            [<aFileFilters>], ;
            [<lSaveAs>], ;
            [<lRestoreDir>], ;
            [<lMultiple>], ;
            [<oParent>], ;
            [<oOwner>] ) -> cFileName

Returns:

 When the file dialog is closed with the "OK" pushbutton, this
 function returns the entire file name as a character string
 including the drive and directory.  If the dialog is not closed
 using the "OK" pushbutton, the return value is the value
 passed as <cDefaultFile>.

Arguments:

<cFileName> is the starting file name to select in the file
dialog window. If no value is passed then a choice of files in
the current directory will be the default.

<cDirectory> is the name of the default directory.  If this
argument is not passed, then the current directory is default.

<cWildCard> is a wildcard string for the type of files to
display in the dialog window.  The default is '*.*' (all files).

<cTitle> is the title of the dialog window.

<aFileFilters> optionally defines filters that are used to
show or hide certain files within the dialog. This is
similar to using wildcards with Shell commands and affects
the range of files selectable by the user. The format of
the array for defining file filters is as follows:

  aFileFilters := { {<cFilterName1>, <cExprList1>},
                    {<cFilterName2>, <cExprList2>},
                   ...,
                    {<cFilterNameN>, <cExprListN>} }

<cFilterName> can be an arbitrary string that defines the
name of the filter in human-readable form. <cExprList>
is a string that defines one or more filter expressions
that a file must match in order to be included in the file list if the filter is active. If more than one filter expression is to be defined, individual expressions must be separated by a semicolon (;). Filter expressions may contain the asterisk (*) wildcard character but no spaces.
If :fileFilters contains the empty array ({}), no file
filters are defined. This is equivalent to the filter
expression "*.*" (include all files).

Example:

aFileFilters := { {"Xbase++ Sources", "*.PRG;*.CH"}, ;
                  {"All Files"      , "*.*"       }  }

This filter definition would cause the file dialog to
display two entries in its list of file filters.
electing the entry "Xbase++ Sources" would include all
.PRG- and .CH-files in the current directory in the list
of files the user can select from. Files not matching
the filter pattern would not be selectable. If the filter
"All Files" is activated, the file dialog would display
all files in the current folder.

<lSaveAs> should be a .T. when a user needs to save a file
(or save it under a different name).

<lRestoreDir> if .TRUE. (default) will restore the system
directory setting.

<lMultiple> if .TRUE. will allow the user to select more than
one file in the file dialog.  It will return a list of files
selected by the user.

<oParent> is the optional parent of the dialog.  If no parent
is given then the parent is the AppDeskTop().

<oOwner> is the optional owner of the dialog.  If no owner
is given then the owner is the parent.

Examples:

 #include "dcdialog.ch"

 FUNCTION XTest()

 LOCAL GetList := {}, cFileName := Space(60), oMsgBox

 DC_GUI(.t.)

 @ 1,1 DCSAY 'Enter BitMap File Name' GET cFileName ;
  POPUP {|c|DC_PopFile(c,'\bitmaps\','*.BMP')} ;
  MESSAGE 'Click on button for file dialog' ;
  INTO oMsgBox

 @ 3,1 DCMESSAGEBOX OBJECT oMsgBox SIZE 30

 DCREAD GUI FIT ADDBUTTONS

 RETURN nil

Files:

_DCFUNCT.PRG/.OBJ, DCLIPX.DLL

See Also:

   dc_popdir()


dc_popfont()

A pop-up dialog for selecting a Font name

DC_POPFONT() is a Font Dialog that can be called from Xbase++ code or in a code-block via the POPUP clause in the DCSAY..GET command. <br><br>

Syntax:

 DC_PopFont( [<cFont>] -> cNewFont

Returns:

 The Compound Name of the font selected (a character string).

Arguments:

<cFont> is the starting font to highlight in the font dialog
window. If no value is passed then the first font will be
the default.

Examples:

 #include "dcdialog.ch"

 FUNCTION XTest()

 LOCAL GetList := {}, cFont := Space(50), oMsgBox

 @ 1,1 DCSAY 'Enter Font Name' GET cFont ;
  POPUP {|c|DC_PopFont(c)} ;
  MESSAGE 'Click on arrow for a Font Picker' ;
  INTO oMsgBox

 @ 3,1 DCMESSAGEBOX OBJECT oMsgBox SIZE 30

 DCREAD GUI FIT ADDBUTTONS

 RETURN cFont

Files:

_DCFONT.PRG/.OBJ, DCLIPX.DLL

See Also:

   dc_presedit()


dc_poppresalign()

A popup dialog for selection Presentation Alignment

DC_POPPRESALIGN() is a popup editor that can be used to edit Presentation Parameters that affect alignment. This function can be called from Xbase++ code or in a code-block via the POPUP clause in the DCSAY..GET command. The following Xbase++ Presentation Parameters are used to define the layout of a dialog item: XBP_PP_ALIGNMENT - Generic Alignment XBP_PP_COL_DA_CELLALIGNMENT - Browse Cell Alignment XBP_PP_COL_HA_ALIGNMENT - Browse Header Alignment XBP_PP_COL_FA_ALIGNMENT - Browse Footer Alignment<br><br> A numeric value is assigned to each of these PP items to establish the alignment options. This numeric value is a bitwise summation of options. DC_PopPresAlign() reads the numeric value and separates the options, allowing each one to be selected individually by GUI dialog checkboxes, then it combines them back into a numeric value to be used with the associated PP.<br><br>

Syntax:

 DC_PopPresAlign( [<nAlign>] ) -> nAlign

Returns:

 A numeric value.

Arguments:

<nAlign> is a numeric value containing the alignment options.

Examples:

 #include 'xbp.ch'

 nAlign := XBPALIGN_LEFT + XBPALIGN_BOTTOM

 nAlign := DC_PopPresAlign( nAlign )

 aPres := { { XBP_PP_COL_FA_ALIGNMENT, nAlign } }

Files:

_DCPRES.PRG, DCLIPX.DLL

See Also:

   dc_presedit()


dc_poppresborder()

A popup dialog for selection Presentation Border

DC_POPPRESBORDER() is a popup editor that can be used to edit Presentation Parameters that affect a border. This function can be called from Xbase++ code or in a code-block via the POPUP clause in the DCSAY..GET command. XbpDialog() and XbpCrt() classes provide the option of selecting a border by assigning a numeric value to the :border iVar. A numeric value is assigned to the iVar to establish the border of the window. DC_PopPresBorder() reads the numeric value and allows a new value to be selected via GUI Radio Buttons.

Syntax:

 DC_PopPresBorder( [<nBorder>] ) -> nBorder

Returns:

 A numeric value.

Arguments:

<nBorder> is a numeric value containing the Border option.

Examples:

 #include 'xbp.ch'

 nBorder := XBPDLG_RAISEDBORDERTHICK_FIXED

 nBorder := DC_PopPresBorder( nBorder )

 oDialog:border = nBorder

Files:

_DCPRES.PRG, DCLIPX.DLL

See Also:

   dc_presedit()


dc_poppreslayout()

A popup dialog for selection Presentation Layout

DC_POPPRESLAYOUT() is a popup editor that can be used to edit Presentation Parameters that affect layout. This function can be called from Xbase++ code or in a code-block via the POPUP clause in the DCSAY..GET command. The following Xbase++ Presentation Parameters are used to define the layout of a dialog item: XBP_PP_COL_DA_FRAMELAYOUT - Browse Data Frame Layout XBP_PP_COL_DA_CELLFRAMELAYOUT - Browse Cell Frame Layout XBP_PP_COL_DA_HILITEFRAMELAYOUT - Browse Hilite Frame Layout XBP_PP_COL_HA_FRAMELAYOUT - Browse Header Frame Layout XBP_PP_COL_FA_FRAMELAYOUT - Browse Footer Frame Layout<br><br> A numeric value is assigned to each of these PP items to establish the frame layout. This numeric value is a bitwise summation of options. DC_PopPresLayout() reads the numeric value and separates the options, allowing each one to be selected individually by GUI dialog checkboxes, then it combines them back into a numeric value to be used with the associated PP.<br><br>

Syntax:

 DC_PopPresLayout( [<nLayout>] ) -> nLayout

Returns:

 A numeric value.

Arguments:

<nLayout> is a numeric value containing the layout options.

Examples:

 #include 'xbp.ch'

 nLayout := XBPFRAME_BOX + XBPFRAME_RECESSED

 nLayout := DC_PopPresLayout( nLayout )

 aPres := { { XBP_PP_COL_DA_FRAMELAYOUT, nLayout } }

Files:

_DCPRES.PRG, DCLIPX.DLL

See Also:

   dc_presedit()


dc_poppressep()

A popup dialog for selection Presentation Separator

DC_POPPRESSEP() is a popup editor that can be used to edit Presentation Parameters that affect separators. This function can be called from Xbase++ code or in a code-block via the POPUP clause in the DCSAY..GET command. The following Xbase++ Presentation Parameters are used to define the separators of a dialog item: XBP_PP_COL_DA_ROWSEPARATOR - Browse Data Row separator XBP_PP_COL_DA_COLSEPARATOR - Browse Data Column separator<br><br> A numeric value is assigned to each of these PP items to establish the separator type. DC_PopPresSep() reads the numeric value and allows a new value to be selected via GUI Radio Buttons.<br><br>

Syntax:

 DC_PopPresSep( [<nSep>] ) -> nSep

Returns:

 A numeric value.

Arguments:

<nSep> is a numeric value containing the separator option.

Examples:

 #include 'xbp.ch'

 nSep := XBPCOL_SEP_DASHED

 nSep := DC_PopPresSep( nSep )

 aPres := { { XBP_PP_COL_DA_COLSEPARATOR, nSep } }

Files:

_DCPRES.PRG, DCLIPX.DLL

See Also:

   dc_presedit()


dc_popscrn()

Restore a screen area from the screen stack

DC_POPSCRN() is used to restore the screen from the screen contents that was pushed onto the stack with DC_PUSHSCREEN().

Syntax:

DC_PopScrn( <aScrnStack> ) -> aScrnStack

Returns:

 An array containing the new contents of the screen stack.

Arguments:

<aScrnStack> is an array that contains screens created by
DC_PUSHSCRN().

Examples:

 aStack := {}
 aStack := dc_pushscrn(aStack)  // save current screen
 cls   // clear the screen
 aStack := dc_pushscrn(aStack,4,10,8,70,.T.,,,,;
          ' Enter a Command ',10)
 cCommand := space(50)
 @ 6,12 get cCommand
 read
 aStack := DC_POPSCRN(aStack)
 aStack := DC_POPSCRN(aStack)

Files:

_DCEXPL.PRG/.OBJ, DCLIPX.LIB

See Also:


dc_poptime()

A pop-up browse for selecting a time

DC_PopTime() is a time picker that can be called from Xbase++ code or in a code-block via the POPUP clause in the DCSAY..GET command.

Syntax:

 DC_PopTime( [<cCurTime>],;
             [<nMinuteIncrement>] ) -> cTime

Returns:

A Character String - the time selected.

Arguments:

<cCurTime> is the starting time to highlight in the picker.

<nMinuteIncrement> is the number of minute increments to display in the
picker.  The default is 5 minutes.

Examples:

#include "dcdialog.ch"

FUNCTION XTest()

LOCAL GetList := {}, cTime := Space(5), oMsgBox

@ 1,1 DCSAY 'Enter Time for this appointment' GET cTime ;
  POPUP {|c|DC_PopTime(c,15)} ;
  MESSAGE 'Click on arrow for a time picker' ;
  INTO oMsgBox

@ 3,1 DCMESSAGEBOX OBJECT oMsgBox SIZE 30

DCREAD GUI FIT ADDBUTTONS

RETURN nil

Files:

_DCCALEN.PRG/.OBJ, DCLIPX.DLL

See Also:

   dc_popdate()


dc_popupbuttonstyle()

Get or Set the default style for DCGET popup buttons

DC_PopupButtonStyle() is a Get-Set function that is used to Set or Get the default configuration object for popup pushbuttons that are automatically added to DCGET objects via the POPUP clause of @ DCSAY..GET.<br><br><br><br><br><br><br><br>

Syntax:

DC_PopupButtonStyle( [<oConfig>] ) -> oOldConfig

Arguments:

<oConfig> is an object of the DC_XbpPushButtonXPConfig() class.

Examples:

oConfig := DC_XbpPushButtonXPConfig():new()

oConfig:radius := 5
oConfig:bgColor := GRA_CLR_CYAN

DC_PopupButtonStyle( oConfig )

Files:

_dcxbutt.prg, dclipx.dll

See Also:

   dc_xbppushbuttonxpconfig()


dc_presadd()

Add Presentation Parameters to a PP Array

DC_PresAdd() is used to add a presentation parameter to a Presentation Parameters array. It will first test to see if parameter already being added already exists in the array and if it does it will overwrite it with the new value. <br><br>

Syntax:

 DC_PresAdd( <aPP>, ;
             <aItem> ) -> aNewPP

Returns:

 An Array.

Arguments:

<aPP> is a Presentation Parameters array that conforms to the
standard Xbase++ specification for Presentation Parameters.

<aItem> is a 2-element array that conforms to the standard
Xbase++ specification for individual items in a Presentation
Parameters array.

Examples:

 aItem := { XBP_PP_DISABLED_BGCLR, GraMakeRGBColor({20,45,80}) }

 aPres := DC_Str2Ar(MYDIALOG->pp)  // get PP from a database

 aPres := DC_PresAdd( aPres, aItem )

Files:

_DCPRES.PRG, DCLIPX.DLL

See Also:

   dc_presedit()


dc_presedit()

A GUI Editor for a Presentation Parameters Array

DC_PresEdit() is used to edit a Presentation Parameters array. This array must conform to the standard Xbase++ specifications for presentation parameters. DC_PresEdit() will display pushbuttons, picklists and popup windows for selecting colors, fonts, borders, alignment, etc. and save the selection to a new array or allow editing of an existing array. The Editor allows provides for saving the PP to source code for pasting into application code.<br><br>

Syntax:

 DC_PresEdit( <aPP> ) -> aNewPP

Returns:

 An Array.

Arguments:

<aPP> is a Presentation Parameters array that conforms to the
standard Xbase++ specification for Presentation Parameters.

Examples:

 aPres := DC_Str2Ar(MYDIALOG->pp)  // get PP from a database

 aPres := DC_PresEdit( aPres )

 MYDIALOG->pp := DC_Ar2Str(aPres)  // store PP back to database

Files:

_DCPRES.PRG, DCLIPX.DLL

See Also:

   dc_presadd()
   dc_browpres()


dc_printbrowse()

Print the contents of a Browse object

DC_PrintBrowse() will print the contents of any browse object that has been derived from XbpBrowse() as a WYSIWIG printout.<br><br>

Syntax:

DC_PrintBrowse( <oBrowse>, ;
                [<aOptions>] ) -> NIL

Arguments:

<oBrowse> is any browse object derived from XbpBrowse().

<aOptions> is an array of print options that conforms to the
array structure created by the DCPRINT OPTIONS command.

Examples:

DCPRINT OPTIONS ORIENTATION 2 ACROBAT TO aOptions

DC_PrintBrowse( oBrowse, aOptions )

Files:

_dcprc.prg, dclipx.dll

See Also:

   DCPRINT OPTIONS


dc_printclipboard()

Print the contents of the ClipBoard (BitMap Only)

DC_PrintClipBoard() will print the contents of the ClipBoard. Only items of type BITMAP will be printed. This function is used in conjunction with DC_Scrn2ClipBoard() to print the contents of a dialog window.

Syntax:

DC_PrintClipBoard( [<lPreview> ] ) -> lStatus

Returns:

A logical .TRUE. if the contents were previewed or printed, .FALSE.
otherwise.

Arguments:

<lPreview> if .TRUE. will preview the contents before allowing
the user to print.  If .FALSE. (default), then the output will
go to the printer without previewing.

Examples:

DC_Scrn2ClipBoard()
DC_PrintClipBoard(.T.)

Files:

_DCPRC.PRG, DCLIPX.DLL

See Also:

   dc_scrn2clipboard()


dc_printercol()

Returns the current Printer Column position

DC_PRINTERCOL() is used as a replacement for PCOL() when using DCPRINT commands to convert existing text-based reports. This function makes it easy to convert reports that are heavily-laden with commands like @ PROW(), PCOL() SAY <text>.

Syntax:

DC_PrinterCol( [<oPrinter>] ) -> nRow

Returns:

A numeric value.

Arguments:

<oPrinter> is the printer object.  If no parameter is passed then
the STATIC printer object created by the last DCPRINT ON command
is the default.

Examples:

#include "dcprint.ch"

procedure Xtest()

USE COLLECT

DCPRINT ON PREVIEW

DCPRINT EJECT

DO WHILE !Eof()

  @ dc_printerrow()+1, 10 DCPRINT SAY COLLECT->descrip
  @ dc_printerrow(), DC_PRINTERCOL()+2 DCPRINT SAY COLLECT->type

  SKIP

  IF dc_printerrow() > 60
    DCPRINT EJECT
  ENDIF

ENDDO

DCPRINT OFF

RETURN

Files:

_DCPRC.PRG, DCLIPX.LIB

See Also:

   dc_printerrow()
   DCPRINT ON


dc_printerdialog()

A Printer Dialog for setting up printing options

DC_PRINTERDIALOG() is a printer dialog that allows the user to choose a printer, font, and other print options when using the DC_PRINTER() class or the DCPRINT commands.

Syntax:

DC_PrinterDialog ( <aOptions> ) -> aOptions

Returns:

 An array with the same structure as the < aOptions > array which
 is passed as a parameter to DC_PrinterDialog().

Arguments:

<aOptions> is an single-dimensional array of printing options.

  Element   Type   Description
 --------- ------ -------------------------------------------
     1       C     Printer Name.  If not empty, then the user
                   will not be allowed to choose the printer.

     2       N     From (first page #). If not empty, then
                   the user will not be allowed to choose
                   the first and last page to print.

     3       N     To   (last page #)

     4       N     Rows (number of print rows) default is 66.
                   If not empty, then the user will not be
                   allowed to choose the number of print rows.

     5       N     Cols (number of print cols) default is 80.
                   If not empty, then the user will not be
                   allowed to choose the number of print
                   columns.

     6       N     Copies (number of copies to print) default
                   is 1.  If not empty, then the user will not
                   be allowed to choose the number of copies.

     7       X     Spare

     8       L     Collate (default is .F.)

     9       L     Print to file (default is .F.)

    10       A     Paper Size (an array of 6 elements) default
                   is ::self:PaperSize().

    11      C/O    Font.  May be a character string with a
                   Font name or a font object.  Default is
                   12.Courier.  If not empty, then the user
                   will not be allowed to choose the font.

    12      X      Spare

    13      L      Fixed.  If .TRUE. (default), will print each
                   character in fixed columns (even when using
                   proportional fonts).  IF .FALSE. will print
                   characters in the same proportion as the
                   chosen font.  If this parameter is passed,
                   then the user will not be allowed to select
                   the fixed option.

    14      L      Pixel.  If. .TRUE., then coordinates will be
                   pixel-based, otherwise they will be text-
                   based.

    15      L      Preview.  If .TRUE. will cause the printed
                   output to be sent to the display rather than the
                   print device.  This causes the methods of the
                   DC_PRINTER() class to write to an XbpDialog() GUI
                   dialog screen rather than to an XbpPrinter()
                   object.

    16             Reserved.

    17      L      All Pages.  If .TRUE. will default to printing
                   all pages.

    18             Reserved.
    19             Reserved.
    20             Reserved.
    21             Reserved.
    22             Reserved.
    23             Reserved.
    24             Reserved.
    25             Reserved.
    26             Reserved.
    27             Reserved.
    28             Reserved.
    29             Reserved.

    30      L      Enable Font Button.  When .TRUE. this will
                   enable the font button for the user to select
                   a print font.

    31             Reserved.

    32      N      Orientation.  1 = Portrait, 2 = Landscape

    33      C      Comment (output only) from Printer driver selected

    34      C      Port (output only) from Printer driver selected.

    35      C      Status (output only) from Printer driver selected.

    36      AN     Margin. May be a numeric value (LEFT margin only)
                   or an array of two numeric values (TOP and LEFT
                   margins. May be negative and/or decimal values.

    37      C      Title.  This is the title of the preview window
                   and the document.  This title will be sent to the
                   spooler as the name of the print job.

    38      L      Stop on Eject.  If .TRUE. the print job will stop
                   when a DCPRINT EJECT command or oPrinter:eject()
                   method is encountered in the program and the
                   preview window will be displayed.  If .FALSE.
                   (default) the print job will continue to run and
                   buffer pages and will not stop until the DCPRINT OFF
                   command or DC_PrinterOff() function is encountered
                   in the program.

    39      L      Hide. A .TRUE. value will hide the previewer window
                   until the command DCPRINT OFF or the function
                   DC_PrinterOff() are encountered in the program.
                   If .FALSE. (default) each page will be visible in
                   the preview window as they are being created.

    40      N      PaperBin. Used to instruct the printer which paper
                   bin to use for the print job.  A #define constant
                   from XBPDEV.CH must be used for this value. Valid
                   constants have the prefix XBPPRN_PAPERBIN_.

    41      N      FormSize. Used to instruct the printer what paper
                   format is being used. Common formats are Letter,
                   Legal or A4. They are selected by their numeric ID
                   which is available as a #define constant from
                   XBPDEV.CH.  Valid constants have the prefix
                   XBPPRN_FORMSIZE_.

    42      L      PrintButton.  A logical .TRUE. (default) will
                   paint a 'Print' button on the preview window,
                   thereby enabling the ability to print while
                   previewing.

    43      L      EnableCancel. A logical .TRUE. (default) will
                   display a dialog window during printing that
                   includes a CANCEL button to cancel the print job.

    44      C      BusyMessage. A message to display while each
                   screen is being created.  Use this clause if your
                   application takes a long time to create a screen.

    45      L      ForceDialog. A logical .TRUE. will force the
                   Printer dialog window to be display for choosing
                   a printer and/or options.  A .FALSE. (default)
                   will suppress the display of the printer dialog
                   if the DEFAULT printer (element 28) is selected
                   or a PRINTER NAME (element 1) is passed.

    46      L      AutoEject. If .TRUE. (default) an automatic page
                   eject will occurs whenever an attempt is made to
                   print past the last print row defined by the
                   SIZE <nRows>, <nCols> command or when an :AtSay()
                   prints text on a row that is a lower numeric
                   value than the last row printed.

    47      L      CopyLoop. Used to disable the sending of the
                   request to the print driver to print multiple
                   copies.  If the user selects copies from the
                   print dialog screen the value selected will be
                   placed in the oPrinter:nCopies variable and the
                   programmer must used this value in a FOR..NEXT
                   loop to print multiple copies.

    48      N      DialogStyle. Allows users of eXPress++ 1.3 and
                   earlier versions to display the same style
                   dialog in their 1.5 applications as was displayed
                   in 1.3.  Xbase++ 1.5 introduced a new
                   XbpPrinterDialog() class which was incorporated
                   in eXPress++ 1.5.  This new dialog is created by
                   the print driver whereas the old dialog was
                   created by eXPress++ and also included a FONT
                   button for selecting a print font.  Style
                   DCPRINT_DIALOG_EXPRESS (defined in DCPRINT.CH)
                   will display the 1.3 style printer dialog.

Files:

_DCPRC.PRG/.OBJ, DCLIPX.LIB

See Also:

   DCPRINT ON


dc_printername()

Retrieve the last printer name selected by user.

DC_PrinterName() is a Get-Set function used to retrieve the last printer name selected by the user from the printer dialog.<br><br>This function is handy when it is necessary to print a second print job to the same printer.

Syntax:

DC_PrinterName() -> cPrinterName

Returns:

A Character string.

Examples:

DCPRINT ON // Users Selects a printer

.. Print some stuff

DCPRINT OFF

DCPRINT ON NAME DC_PrinterName() // Print to last selected printer

.. Print some more stuff

DCPRINT OFF

Files:

_DCPRC.PRG

See Also:

   DCPRINT ON


dc_printerobject()

Return a reference to the static printer object

DC_PRINTEROBJECT() returns the static printer object created by the DCPRINT ON command or the DC_Printer() class. In single- threaded environments, programming reports can be simplified by eliminating the need to reference the printer object when using various DCPRINT commands. If the PRINTER <oPrinter> clause is not used with the commands then the static printer object is used. The static object is posted to DC_PRINTEROBJECT() when a new DCPRINT ON command is issued and is set to a NIL when the DCPRINT OFF command is used.<br><br> When programming in a multi-threaded environment, the PRINTER clause must be used with all DCPRINT commands to insure that the correct object is referenced.<br><br>

Syntax:

DC_PrinterObject( [<oObject>], ;
                  [<lPost>] ) -> oPrinter

Returns:

 An object.

Arguments:

<oObject> contains a pointer to a printer object to post to the
static variable when <lPost> is .TRUE.  This is the object that
will be returned when DC_PRINTEROBJECT() is called with no
parameters.

Files:

_DCPRC.PRG, DCLIPX.LIB

See Also:

   dc_printeron()
   DCPRINT ON


dc_printeroff()

Destroy a printer object

DC_PRINTEROFF() destroys a printer object that was created with DC_PRINTERON().

Syntax:

DC_PrinterOff( [<oPrinter>] ) -> nil

Arguments:

<oPrinter> is the printer object.  If no parameter is passed then
the STATIC printer object created by the last DCPRINT ON command
is the default.

Examples:

PROCEDURE Xtest()

LOCAL oPrinter

USE COLLECT NEW SHARED

BEGIN SEQUENCE

oPrinter := dc_printeron()

IF Valtype(oPrinter) # 'O' .OR. !oPrinter:lActive
  BREAK
ENDIF

oPrinter:AtSay(24,10,'    Description:')
oPrinter:AtSay(25,10,'           Type:')
oPrinter:AtSay(26,10,'       Sub-Type:')
oPrinter:SetFont('14.Terminal')
oPrinter:AtSay(24,32,COLLECT->descrip)
oPrinter:AtSay(25,32,COLLECT->type)
oPrinter:AtSay(26,32,COLLECT->sub_type)
oPrinter:Eject()

END SEQUENCE

DC_PRINTEROFF()

CLOSE

RETURN

Files:

_DCPRC.PRG, DCLIPX.LIB

See Also:

   dc_printeron()
   DCPRINT OFF


dc_printerok()

Test whether or not the user aborted the Print process

DC_PRINTEROK() is used to test whether the user clicked on "Abort" when printing or previewing a report.

Syntax:

DC_PrinterOk( [<oPrinter>] ) -> lStatus

Returns:

A Logical .FALSE. if the user aborted the print/preview, otherwise
a logical .TRUE.

Arguments:

<oPrinter> is the printer object.  If no parameter is passed then
the STATIC printer object created by the last DCPRINT ON command
is the default.

Examples:

#include 'dcprint.ch'

PROCEDURE Xtest( lPreview )

LOCAL nSaveRec

USE COLLECT NEW SHARED

nSaveRec := RecNo()
GO TOP

IF lPreview
  DCREPORT FORM collect XBP FONT '10.Courier' ;
        TITLEFONT '10.Helv.Bold' HEADFONT '10.Courier.Bold' PREVIEW ;
        WHILE {||DC_PRINTEROK()}
ELSE
  DCREPORT FORM collect XBP FONT '10.Courier' ;
        TITLEFONT '10.Helv.Bold' HEADFONT '10.Courier.Bold' ;
        WHILE {||DC_PRINTEROK()}
ENDIF

GO nSaveRec

RETURN

Files:

_DCPRC.PRG, DCLIPX.LIB

See Also:

   DCPRINT ON


dc_printeron()

Create a printer class object for @..SAY style printing

DC_PRINTERON() creates a printer class which is used to create reports that use row/column addressing identical to the @..SAY addressing used by Clipper. This class provides for an easy migration of existing reports so that they may use the more powerful features of the Windows print manager like font selection and selection of a network printer.<br><br> DC_PRINTERON() also posts the printer object to a static variable which can be accessed at any time via DC_PRINTEROBJECT().

Syntax:

DC_PrinterOn( { <cPrinterName>, ;
                <nFrom>, ;
                <nTo>, ;
                <nRows>, ;
                <nCols>, ;
                <nCopies>, ;
                <lSelection>, ;
                <lCollate>, ;
                <lToFile>, ;
                <aPaperSize>, ;
                <ocFont>, ;
                <oFontDlg>, ;
                <lFixed>, ;
                <lPixel>, ;
                <lPreview>, ;
                <aViewPort> } ) -> oPrinter

Arguments:

<aOptions> is an single-dimensional array of printing options.

  Element   Type   Description
 --------- ------ -------------------------------------------
     1       C     <cPrinterName> is the Printer Name.  If
                   empty, then a printer dialog will appear for
                   the user to select printing options.

     2       N     <nFrom> is the first page #. If not empty, then
                   the user will not be allowed to choose
                   the first and last page to print.

     3       N     <nTo> is the last page #

     4       N     <nRows> (number of print rows) default is 66.
                   If not empty, then the user will not be
                   allowed to choose the number of print rows.

     5       N     <nCols> (number of print cols) default is 80.
                   If not empty, then the user will not be
                   allowed to choose the number of print
                   columns.

     6       N     <nCopies> (number of copies to print) default
                   is 1.  If not empty, then the user will not
                   be allowed to choose the number of copies.

     7       X     <lSelection> Spare

     8       L     <lCollate> is for Collate. (default is .F.)

     9       L     <lToFile> is Print to file (default is .F.)

    10       A     <aPaperSize> is the Paper Size (an array of
                   6 elements) default is ::self:PaperSize().

    11      C/O    <ocFont> is the Font.  May be a character
                   string with a Font name or a font object.
                   Default is 12.Courier.  If not empty, then
                   the user will not be allowed to choose the
                   font.

    12      X      <oFontDlg> Spare

    13      L      <lFixed>  If .TRUE. (default), will print each
                   character in fixed columns (even when using
                   proportional fonts).  IF .FALSE. will print
                   characters in the same proportion as the
                   chosen font.  If this parameter is passed,
                   then the user will not be allowed to select
                   the fixed option.

    14      L      <lPixel>  If. .TRUE., then coordinates will be
                   pixel-based, otherwise they will be text-

    15      L      <lPreview>  If .TRUE. will cause the printed
                   output to be sent to the display rather than the
                   print device.  This causes the methods of the
                   DC_PRINTER() class to write to an XbpDialog() GUI
                   dialog screen rather than to an XbpPrinter()
                   object.

    16      A      <aViewPort>  A 4 element array defined the
                   View Port window.

Examples:

PROCEDURE Xtest()

LOCAL oPrinter

USE COLLECT NEW SHARED

BEGIN SEQUENCE

oPrinter := DC_PRINTERON()

IF Valtype(oPrinter) # 'O' .OR. !oPrinter:lActive
  BREAK
ENDIF

oPrinter:AtSay(24,10,'    Description:')
oPrinter:AtSay(25,10,'           Type:')
oPrinter:AtSay(26,10,'       Sub-Type:')
oPrinter:SetFont('14.Terminal')
oPrinter:AtSay(24,32,COLLECT->descrip)
oPrinter:AtSay(25,32,COLLECT->type)
oPrinter:AtSay(26,32,COLLECT->sub_type)
oPrinter:Eject()

END SEQUENCE

dc_printeroff()

CLOSE

RETURN

Files:

_DCPRC.PRG, DCLIPX.LIB

See Also:

   DCPRINT ON


dc_printerporttoname()

Returns name of a Printer that is assigned to a specified Port.

DC_PrinterPortToName() is used to return the name of a printer that is assigned to a specified port.

Syntax:

DC_PrinterPortToName( <cPort> ) -> cPrinterName

Returns:

A character string.

Arguments:

<cPort> is the printer port.

Examples:

cPrinterName := DC_PrinterPortToName( 'LPT1' )

Files:

_DCPRC.PRG, DCLIPX.DLL


dc_printerrow()

Returns the current Printer Row position

DC_PRINTERROW() is used as a replacement for PROW() when using DCPRINT commands to convert existing text-based reports. This function makes it easy to convert reports that are heavily-laden with commands like @ PROW(), <col> SAY <text>.

Syntax:

DC_PrinterRow( [<oPrinter>] ) -> nRow

Arguments:

<oPrinter> is the printer object.  If no parameter is passed then
the STATIC printer object created by the last DCPRINT ON command
is the default.

Examples:

#include "dcprint.ch"

procedure Xtest()

USE COLLECT

DCPRINT ON PREVIEW

DCPRINT EJECT

DO WHILE !Eof()

  @ DC_PRINTERROW()+1, 10 DCPRINT SAY COLLECT->descrip
  @ DC_PRINTERROW(), dc_printercol()+2 DCPRINT SAY COLLECT->type

  SKIP

  IF DC_PRINTERROW() > 60
    DCPRINT EJECT
  ENDIF

ENDDO

DCPRINT OFF

RETURN

Files:

_DCPRG.PRG, DCLIPX.LIB

See Also:

   dc_printercol()
   DCPRINT ON


dc_printfile()

Print an ASCII file using Windows Print Driver

DC_PRINTFILE() is used to print or preview the contents of an ASCII file. xxxxxx

Syntax:

DC_PrintFile( [<cFileName>], ;
              [<lPreview>], ;
              [<cFont>], ;
              [<aOptions>] ) -> lStatus

Returns:

A Logical .FALSE. if the user aborted the print/preview, otherwise
a logical .TRUE.

Arguments:

<cFileName> is the name of the ASCII file to print.  If no
parameter is passed, a dialog window will appear prompting the
user for a file name.

<lPreview> if .TRUE. will display the contents of the file in a
preview window.  If .FALSE., a printer selection dialog window
will appear and the output will be sent to the selected printer
device.

<cFont> is a character string that conforms to standard Xbase++
font definitions.  The default is '8.Courier New'.

<aOptions> is an options array created with the DCPRINT OPTIONS
command.

Examples:

/*
This example uses DC_PrintFile() to simplify the conversion of
old Clipper reports to using the Windows print driver.
*/

cPrintFile := 'REPORT.TXT'
SET PRINTER TO cPrintFile
SET DEVICE TO PRINT
...Clipper printer commands
SET DEVICE TO SCREEN
SET PRINTER TO
DC_PRINTFILE(cPrintFile)

Files:

_DCPRC.PRG, DCLIPX.LIB

See Also:

   DCPRINT OPTIONS


dc_printimage()

WYSIWIG print of a selected GUI object

DC_PrintImage() is a WYSIWIG function that prints the screen image of an object.

Syntax:

DC_PrintImage( <oXbp>, ;
               [<nMode>] ) -> nil

Returns:

Nil.

Arguments:

<oXbp> is the object to print.

<nMode> if a 1 (default) will print only the selected object.
<nMode> if a 2 will print all the tabpages within a group,
provided that <oXbp> is an object of the type XbpTabPage.

Examples:

Run XDEMO.EXE then place the mouse over any object and press
the middle mouse button.

* -----------

STATIC FUNCTION Xdemo_Handler( nEvent, mp1, mp2, oXbp, oDlg, aGetList )

LOCAL oPrintMenu, GetList[0]

IF nEvent == xbeM_MbDown

  DCSUBMENU oPrintMenu PARENT oXbp

    DCMENUITEM 'Print WYSIWYG (Current Object)' PARENT oPrintMenu ;
      ACTION {||DC_PrintImage(oXbp,1)} ;
      WHEN {||!oXbp:isDerivedFrom('XbpDialog')}

    DCMENUITEM 'Print WYSIWYG (All TabPages)' PARENT oPrintMenu ;
      ACTION {||DC_PrintImage(oXbp,2)} ;
      WHEN {||oXbp:isDerivedFrom('XbpDialog')}

   DCREAD GUI PARENT AppDeskTop() EXIT

   oPrintMenu:popup( oXbp, mp1, 1 , XBPMENU_PU_DEFAULT + XBPMENU_PU_MOUSE_RBDOWN )

   RETURN DCGUI_IGNORE

ENDIF

RETURN DC_HelpHandler( nEvent, mp1, mp2, oXbp, oDlg, GetList )

Files:

_DCPRC.PRG, DCLIPX.LIB, DCLIPX.DLL

See Also:

   DCPRINT ON


dc_printpreviewacrobat()

A print previewer that uses the Acrobat Reader

DC_PrintPreviewAcrobat() is used to display the Acrobat Reader (Adobe) in a window to be used as the print previewer for the DCPRINT ON command.<br><br>The options for how the preview is to be displayed are controlled by DC_PrintPreviewAcrobatOpt().<br><br>

Syntax:

DC_PrintPreviewAcrobat( <cPDFName>, ;
                        [<cTitle>] ) -> nil

Returns:

Nil

Arguments:

<cPDFName> is the name of the Acrobat File (*.PDF format) to
preview.

<cTitle> is the title of the window.  If this parameter is
not used, then the file name will be displayed as the
title.

Notes:

To insure that the Acrobat Reader OCX runs correctly, usethe DC_JazzAgeKey() function to post your individual JazzAgekey. If this is not done, then the JazzAge "demonstration"dialog may be displayed.

Examples:

aOptions := { 2, oDialog:drawingArea, '5' }

DC_PrintPreviewAcrobatOpt( aOptions )

DC_PrintPreviewAcrobat( 'MYREPORT.PDF', 'My Report' )

Files:

_DCPRC.PRG, DCLIPX.DLL

See Also:

   dc_printpreviewacrobatopt()
   DCPRINT ON
   dc_jazzagekey()


dc_printpreviewacrobatopt()

Sets the options for the Acrobat previewer

DC_PrintPreviewAcrobatOpt() is a Get-Set function that is used to set the options for the preview window displayed by DC_PrintPreviewAcrobat().<br><br>

Syntax:

DC_PrintPreviewAcrobatOpt( [<aOptions>] ) -> aOldOptions

Returns:

An array.

Arguments:

<aOptions> is an array of options:

Element  Type   Description
-------  ----   ----------------------------------------
  [1]     N     Modal State (1 = Modeless, 2 = Modal)

  [2]     O     Parent Window.  Default is AppDeskTop()

  [3]     C     Acrobat OCX version.  Default is '5'.  This is
                ignored if element 8 is a value of 3.

  [4]     B     A code block to evaluate before the viewer
                window is displayed.  Parameters passed to code
                block are the XbpDialog() object and the OCX
                object.

  [5]     B     A code block to evaluate when the viewer window
                is closed.  Parameters passed to code block are
                the XbpDialog() object and the OCX object.

  [6]     L     Add Ok/Cancel buttons.  Default is .T.

  [7]     C     Driver Name. Default is "Win2PDF"

  [8]     N     1 - Use Acrobat control (default)
                2 - Use Universal Web Browser control
                3 - Use RunShell() to call Acrobat Reader

                NOTE: Using the Universal Web Browser Control will
                eliminate a memory leak in the AcroRd32.exe process
                that is spawned from the ActiveX control, however
                the window closes slower.

  [9]     C     The path to the directory where temporary *.PDF
                files are created.

  [10]    L     A logical .TRUE. if the temporary file name is the
                same as the title.  A logical .FALSE. if the temporary
                file name is a cryptic name.

Examples:

aOptions := { 2, oDialog:drawingArea, '5' }

DC_PrintPreviewAcrobatOpt( aOptions )

DC_PrintPreviewAcrobat( 'MYREPORT.PDF', 'My Report' )

Files:

_DCPRC.PRG, DCLIPX.DLL

See Also:

   dc_printpreviewacrobat()
   DCPRINT ON


dc_printpreviewimagewriteropt(

Sets the options for the Image Writer previewer

DC_PrintPreviewImageWriterOpt() is a Get-Set function that is used to set the options for the preview window displayed when using the IMAGEWRITER clause of DCPRINT ON.<br><br>

Syntax:

DC_PrintPreviewImageWriterOpt( [<aOptions>] ) -> aOldOptions

Returns:

An array.

Arguments:

<aOptions> is an array of options:

Element  Type  Description
-------  ----  ----------------------------------------
  [1]     C    Driver Name.
               Default is "Microsoft Office Document Image Writer"

  [2]     C    The path to the directory where temporary *.MDI
               files are created.

  [3]     L    A logical .TRUE. if the temporary file name is the
               same as the title.  A logical .FALSE. if the temporary
               file name is a cryptic name.

Files:

_DCPRC.PRG, DCLIPX.DLL

See Also:

   dc_printpreviewacrobatopt()
   DCPRINT ON


dc_printpreviewxpswriter()

A print previewer that uses the Microsoft XPS Document Writer

DC_PrintPreviewXPSWroter() is used to display the Microsoft XPS Document Writer in a window to be used as the print previewer for the DCPRINT ON command.<br><br>The options for how the preview is to be displayed are controlled by DC_PrintPreviewXPSWriterOpt().<br><br>

Syntax:

DC_PrintPreviewAcrobat( <cPDFName>, ;
                        [<cTitle>], ;
                        [<lNoSpawn>] ) -> nil

Returns:

Nil

Arguments:

<cXPSName> is the name of the XPS Document File (*.XPS format) to
preview.

<cTitle> is the title of the window.  If this parameter is
not used, then the file name will be displayed as the
title.

<lNoSpawn> is a logical .TRUE. to supress the spawning of the
printed documented to the XPS viewer at the completion of the
print job.  Default is .FALSE.

Files:

_DCPRC.PRG, DCLIPX.DLL

See Also:

   dc_printpreviewxpswriteropt()
   DCPRINT ON


dc_printpreviewxpswriteropt()

Sets the options for the XPS Document Writer previewer

DC_PrintPreviewXpsWriterOpt() is a Get-Set function that is used to set the options for the preview window displayed when using the XPSWRITER clause of DCPRINT ON.<br><br>

Syntax:

DC_PrintPreviewXPSWriterOpt( [<aOptions>] ) -> aOldOptions

Returns:

An array.

Arguments:

<aOptions> is an array of options:

Element  Type  Description
-------  ----  ----------------------------------------
  [1]     C    Driver Name.
               Default is "Microsoft XPS Document Writer"

  [2]     C    The path to the directory where temporary *.XPS
               files are created.

  [3]     L    A logical .TRUE. if the temporary file name is the
               same as the title.  A logical .FALSE. if the temporary
               file name is a cryptic name.

Files:

_DCPRC.PRG, DCLIPX.DLL

See Also:

   dc_printpreviewxpswriter()
   DCPRINT ON


dc_progload()

Load a Program from the Program Dictionary to an Array

DC_PROGLOAD() is used to load a program from the DCPROG.DBF Program Catalog file into an array for later processing with DC_INTERPRET().<br><br>

Syntax:

DC_ProgLoad( [<cProgName>], ;
             [<lMessage>], ;
             [<lCache>], ;
             [@<cProgram>] ) -> aProgram

Returns:

 If the program is to be interpreted, a multi-dimensional array
 containing the program commands, compiler pointers, etc. is
 returned, otherwise a NIL is returned.

Arguments:

<cProgName> is the Tag Name of the program in the DCPROG.DBF
Program Catalog file.  If no parameter is passed, then a pick-
list of available programs will be displayed.

<lMessage> if .TRUE. (default) will display an error message
if the program could not be found in the DCPROG.DBF
dictionary.  If .FALSE., then no message will be displayed.

@<cProgram> is an optional character string (memo text)
containing the program to convert to an array. If the program
is found in the dictionary the text of the program will be
stored in this variable.

<lCache> if .TRUE. (default) will store the output array into
a cache memory for faster loading of the program if it is
called again.  If <lCache> is .FALSE. or if DC_MEMCACHE()
is set to 0, then the program will be loaded each time from
the dictionary file.

 @<lCompile> is an optional variable that will contain a .TRUE.
 if the loaded program is to be compiled and a .FALSE. if the
 loaded program is to be interpreted.

Examples:

 -- Example 1 --

 /* Program stored in 'TEST' record of DCPROG.DBF :

 PARAMETERS a,b,c,d
 CLS
 USE CUSTOMER
 nReceivables := 0
 DO WHILE !EOF()
   ? 'Record',RecNo()
   ?? FieldGet(a)
   ?? FieldGet(b)
   ?? FieldGet(c)
   ?? FieldGet(d)
   IF !EMPTY(phone1)
     ?? phone1
   ELSEIF !EMPTY(phone2)
     ?? phone2
   ENDIF
   nReceivables += balance
 ENDDO
 RETURN nReceivables
 */

 aProgram := DC_PROGLOAD('TEST')
 nMoneyDue := DC_Interpret( aProgram, { 3, 5, 6, 9 } )
 ? nMoneyDue
 wait

Files:

_DCPROG.PRG

See Also:

   dc_interpret()
   dc_progmaint()


dc_progmaint()

Maintain the DCPROG.DBF Program Dictionary File

DC_PROGMAINT() is used to maintain a database catalog of programs for later interpreting with DC_PROGRAM(). This system in intended for creating small programs that may be run from the dot-prompt, menus, data-entry validations, etc. DC_PROGMAINT() provides an editor, search routines, print routines, etc. Programs are saved in a MEMO field in the DCPROG.DBF/.DBT file. These "interpreted" programs are not intended to replace compiled code but are instead a handy way of creating additional on-the-fly functions and procedures to give a data-driven system some extra convenience and functionality.<br><br>

Syntax:

 DC_ProgMaint() -> nil

Returns:

 Nil.

Arguments:

 None.

Files:

_DCPROG.PRG

See Also:

   dc_interpret()
   dc_progload()


dc_program()

Run a Program from the Program Dictionary

DC_PROGRAM() is used to load a program from the DCPROG.DBF program catalog database and execute the program using the interpreter or runtime compiler. Programs in the dictionary are pre-designated as "Interpreted" or "Compiled".<br><br> Interpreted programs may contain any command that can be intrepreted at the dot-prompt plus the same type of structural elements as standard Clipper programs such as DO..WHILE and FOR..NEXT loops, IF..ELSE, DO..CASE statements, PARAMETERS statement and RETURN value, however they cannot contain CLASS statements, FUNCTION statements, LOCALS or STATICS. If a program is designated to be Interpreted, the program is passed to the DC_INTERPRET() function.<br><br> Compiled programs may contain any type of code that can be compiled with the XPP.EXE compiler. IF a program is designated to be Compiled, the program is first compiled by the DC_COMPILE() function, then loaded into memory with the DC_OBJLOAD() function and executed.<br><br><br><br>

Syntax:

 DC_Program( [<cProgName>], ;
             [<aParams>], ;
             [<cProgram>], ;
             [<lCompile>] ) -> Nil

Returns:

 Nil.

Arguments:

<cProgName> is the Tag Name of the program in the DCPROG.DBF
Program Catalog file.  If no parameter is passed, then a pick-
list of available programs will be displayed.  If an array
<aProgram> is passed then it must conform to the structure
of the array returned by DC_PROGLOAD() or interpreted
programs.

<aParams> is a single-dimensional array of parameters to pass
to the program being interpreted.  There should be one element
in the array for each parameter included in the PARAMETERS
statement in the interpreted program.  If less parameters are
passed than specified in the PARAMETERS statement, the unpassed
parameters will be initialized to NIL.

<cProgram> is an optional character string.  If <lCompile> is
.TRUE. then it must contain the full path name of the program
to compile and run.  If <lCompile> is .FALSE. then it must
contain the text of the program to interpret. If this parameter
is passed, then the Program Catalog will not be searched and
<cProgName> will be ignored.

<lCompile> if .TRUE. will compile <cProgram> and load it for
execution of any functions or procedures contained in <cProgram>.
<lCompile> if .FALSE. (default) will interpret <cProgram>.

Files:

_DCPROG.PRG

See Also:

   dc_interpret()
   dc_progload()
   dc_progmaint()


dc_progress()

Display a Progress bar

DC_PROGRESS() is used to display a progress bar for displaying the progress of any operation. The progress bar will fill in the specified area with a graphic progress bar and the text value in % of the actual progress.

Syntax:

DC_Progress ( <nMode>, ;
             [<nValue>], ;
             [<nMaxValue>], ;
             [<nStRow>], ;
             [<nStCol>], ;
             [<nEnCol>], ;
             [<lBox>], ;
             [<cColors>] ) -> Nil

Returns:

 Nil

Arguments:

<nMode> is a number 0,1, or 2 depending on the function
desired:

 0 - Initialize Static values and display starting bar
 1 - Refresh bar with current value
 2 - Terminate and restore screen

<nValue> is the "start" value to evaluate if <nMode> is 0 and
the "current" value to evaluate if <nMode> is 1.  This must be
less than or equal to <nMaxValue>.  If this parameter is not
passed then a static value will automatically be incremented
by a value of 1.

<nMaxValue> is the maximum numeric value.

<nStRow> is the start display row.  This parameter is used
only if <nMode> is 0.

<nStCol> is the start display column.  This parameter is used
only if <nMode> is 0.

<nEnCol> is the end display column.  This parameter is used
only if <nMode> is 0.

<lBox> if .TRUE. (default) will paint a box around the progress
bar starting at the passed coordinates, otherwise the progress
bar only will be painted starting at the passed coordinates.

<cColors> is a character string containing 2 color specfications
separated by a comma.  The first color is the color of the box,
the second is the color of the progress bar.  If no parameter
is passed, then the current system color will be used for both
colors.

Examples:

 ? 'Recalling all records'
 DC_PROGRESS( 0,,RecCount() )
 dbSetOrder(0)
 go top
 do while !Eof()
   DC_PROGRESS( 1, RecNo() )
   dbRecall()
   SKIP
 enddo
 DC_PROGRESS( 2 )

Files:

_DCODD2.PRG/.OBJ,DCLIPX.LIB

See Also:

   dc_odometer()
   dc_odblock()
   dc_working()


dc_purge()

Purge duplicate records from a database

DC_PURGE() is used to remove records from a database that have duplicates based on a test of specified fields. The purged records will be marked as *deleted* but will not actually be removed from the data file until the file is packed. This will allow you to BROWSE the file and monitor the purged information before completing the final reduction.<br><br> DC_PURGE() actually creates a temporary index file based on an expression that is passed or created from the pop-up index builder.<br><br> Purged records can be written to a new data file for recovery at any time.<br><br>

Syntax:

DC_Purge ( [<cIndexExpr>], ;
           [<cFileName>], ;
           [<cRetainExpr>], ;
           [<lMax>], ;
           [<cFieldName>] ) -> Nil

Returns:

 Nil.

Arguments:

<cIndexExpr> is an expression of field names to use in determining
how to determine the duplication of records.  For example, if
you want to purge records that have duplication of information
in which LAST_NAME, FIRST_NAME and STREET are identical, then
use "UPPER(LAST_NAME+FIRST_NAME+STREET)" as    the expression.

If <cIndex> expression is not given then a window will appear
with a user prompt to enter an expression or to press ALT-F for
the index builder.  If ALT-F is pressed, a pick-list of fields
will appear to aid in building the expression.

<cFileName> is an optional parameter that is the name of a new
database which will contain the purged records.  If no argument
is given, then no database will be created, instead the delete
flag of the purged records will be set.

<cRetainExpr> is an expression that determines which record of
the set of duplicate records to retain (not mark for deletion).
The default is "RECNO()".

<lMax> if .TRUE. will retain the maximum value.  If .FALSE.
(default) will retain the minimum value.

<cFieldName> is the name of an optional numeric field in the
database being purged.  This field is used to write a number
from 0 to N.  If there are no duplicates, then a 0 will be written
to the record.  If there ARE   duplicates then a 1 will be written
to the RETAINED record and a number from 2 to N will be written to
each duplicate.

Examples:

 /* Purge all duplicate records that have an exact match
    for Last Name, First Name, Phone Number and Street.
    Retain the record that has the latest Mail Date */

 . USE MAILLIST
 . DC_PURGE("LAST+FIRST+PHONE+STREET",,"MAIL_DATE",.t.)
 . dc_browsedb()
 . dc_pack()

Files:

_DCPURGE.PRG

See Also:


dc_pushbuttonstyle()

Get or Set the default style for legacy push buttons

DC_PushButtonStyle() is a Get-Set function that is used to Set or Get the default configuration object for "legacy" pushbuttons. <br><br>Legacy pushbuttons are pushbuttons that were created with the @ DCPUSHBUTTON or DCADDBUTTON commands. The objects created from the commands are derived from the XbpPushButton class and have the basic look of windows pushbuttons.<br><br>The DC_XbpPushButtonXP class is also derived from the XbpPushButton class however it used the OWNERDRAW capability of the class and therefore supports a much richer and visually appealling class of pushbuttons.<br><br>DC_PushButtonStyle() is used to automatically convert all buttons created by the legacy commands to using the new class and thereby giving legacy applications a new look with a very minor code addition to the beginning of the application.<br><br><br><br>

Syntax:

DC_PushButtonStyle( [<oConfig>] ) -> oOldConfig

Arguments:

<oConfig> is an object of the DC_XbpPushButtonXPConfig() class.

Examples:

oConfig := DC_XbpPushButtonXPConfig():new()

oConfig:radius := 20
oConfig:bgColor := GRA_CLR_CYAN

DC_PushButtonStyle( oConfig )

Files:

_dcxbutt.prg, dclipx.dll

See Also:

   @ DCPUSHBUTTON
   DCADDBUTTON
   @ DCPUSHBUTTONXP
   dc_xbppushbuttonxpconfig()


dc_putkey()

Stuff any keyboard value into Keyboard Buffer

DC_PUTKEY() will stuff any INKEY() value into the keyboard buffer, including function keys, ALT-<n> keys, etc. DC_PUTKEY() functions similar to the KEYBOARD command except that only one key may be stuffed per call and the keyboard buffer is not cleared.

Syntax:

DC_PutKey ( <nKey> | <cKey> | <aKeys> ) -> nil

Returns:

 nil

Arguments:

<nKey> is the INKEY() value of the key to stuff in the
keyboard buffer.  This must be a value between -39
and 320.

<cKey> is a character string value to stuff in the keyboard
buffer.

<aKeys> is a single dimensional array consisting of elements
that are single characters or Inkey() values or both.

Examples:

 -- Example 1 --

 #include 'inkey.ch'
 DC_PUTKEY( K_ESC )

 -- Example 2 --

 // Add a set of keys to keyboard buffer
 DC_PutKey( { K_ALT_F, K_F10, K_ALT_K } )

 -- Example 3 --

 // Stuff a character string in the keyboard buffer
 DC_Putkey( 'USE JUNK' + CHR(13) )

Files:

_DCPUTK.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_mousekey()


dc_qout()

Send data to the default CRT window

DC_QOUT() and DC_QQOUT() are used to send data to the default CRT window when debugging GUI applications. The CRT window is used with the DC_QOUT() function to echo any information. Using the ? command or Qout() function will cause an error if SetAppWindow() is not set to an XbpCrt() object. This makes it very difficult to use ? or Qout() inside GUI applications where SetAppWindow() is pointing to a GUI object like an XbpDialog(). <br><br>

Syntax:

DC_QOut ( [<xText>] ) -> nil

Returns:

 An array of information about the screen object that is used
 with DC_Say(), DC_Cls() and DC_Impl().

Arguments:

<xText> is any variable.

Examples:

 DC_QOUTWINDOW()

 DC_QOUT( "This is a test" )

Files:

_DCQOUT.PRG/.OBJ, DCLIPX.LIB

See Also:

   DCQOUT
   dc_qoutwindow()


dc_qoutwindow()

Establish or Create a CRT window for debugging GUI apps

DC_QOUTWINDOW() is used to Create a CRT window for debugging GUI applications. The CRT window is used with the DC_Qout() function and DCQOUT command to echo any information. Using the ? command or Qout() function will cause an error if SetAppWindow() is not set to an XbpCrt() object. This makes it very difficult to use ? or Qout() inside GUI applications where SetAppWindow() is pointing to a GUI object like an XbpDialog(). <br><br>

Syntax:

DC_QOutWindow ( [<oCrt>], ;
                [<bEval>], ;
                [<lAppWindow>] ) -> oOldCrtWindow

Returns:

 An array of information about the screen object that is used
 with DC_Say(), DC_Cls() and DC_Impl().

Arguments:

<oCrt> is a pointer to an existing XbpCrt() object to post
as the object for DCQOUT commands.  If no argument is passed
then a new XbpCrt() object will be created.

<bEval> is a code block to evaluate after the XbpCrt() window
is created.  The Crt object is passed to the code block.

<lAppWindow> if .TRUE. will set the Crt object as the
application window with SetAppWindow().

Examples:

 DC_QOUTWINDOW()

 DCQOUT "This is a test"

Files:

_DCQOUT.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_qout()
   DCQOUT


dc_random()

Return a random number between 0 and 255

DC_RANDOM() is used to generate a random number from 0 to 255.

Syntax:

 DC_Random ( [<nMax>] ) -> nNumber

Returns:

 A numeric value.

Arguments:

<nMax> is a value of the maximum number size to return.
If no parameter is passed then the maximum size will
be 255.  If a number greater than 255 is passed then
the maximum size will still be 255.

Examples:

 . ? DC_RANDOM()
 137
 . ? DC_RANDOM(10)
 6

Files:

_DCSCRNS.PRG, DCLIP2.DLL


dc_rddsel()

Select a database driver

DC_RddSel() is used to select a database driver (DBE) from a picklist of available drivers.<br><br>

Syntax:

 DC_RddSel( [<cDbe>], ;
            [<lSet>] ) -> cDbe

Returns:

 A Character string containing the name of the selected database
 driver.

Arguments:

<cDbe> is the database driver to select.

<lSet> if .TRUE. will load and set the selected driver as the
default.  The default is .FALSE.

Examples:

 . ? DC_RddSel()  // return the name of selected driver
 . DC_RddSel( nil, .t. ) // select a driver from pick list.

Files:

_dcrdd.prg

See Also:


dc_readalt()

Establish alternate usage of Ctrl-END in table of Gets

DC_READALT() provides an alternate usage of K_CTRL_END and K_CTRL_W in a table of GETS when using DC_READMODAL(). This function is used to set the Read mode to cause K_CTRL_END and K_CTRL_W to go to the last GET. The default condition is that K_CTRL_END and K_CTRL_W will terminate the read.

Syntax:

DC_ReadAlt ( [<lMode>] ) -> lMode

Returns:

 The current mode.

Arguments:

<lMode> if .TRUE. will Set the alternate mode.  The default
is .FALSE.

Files:

_DCGETSY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()
   dc_readnav()


dc_readapick()

Pops up array pick-list if GET not valid or double-clicked

DC_READAPICK() is used to validate the value in a GET based on a passed array and pop-up a pick-list if the input is not valid. DC_READAPICK() should be used as a VALID function in a GET statement. The pick-list will be displayed whenever the input is not valid or when the mouse is double- clicked.

Syntax:

DC_ReadAPick ( <xGetValue>, ;
               <aPickList>|<bPickList>, ;
               [<nStRow>], ;
               [<nStCol>], ;
               [<nEnRow>], ;
               [<nEnCol>], ;
               [<lAccept>], ;
               [<lStringList>], ;
               [<nSubList>], ;
               [<lAddToGet>] ) -> lValid

Returns:

 A .TRUE. if the value entered for <getvar> is valid,
 .FALSE. otherwise.

Arguments:

<xGetValue> is the current value in the GET variable.

<aPickList> is an array of valid values for <getvar>.
If this is a single-dimensional array, then the array
items will be displayed in the pick-list.  If it's a
multi-dimensional array, then the first element of each
item will be used for the validation, the second element
of each item will be displayed in the pick-list, and the
third (optional) element is a HELP CODE (character string)
which will be passed on to the DC_HelpF1() function to
display context-specific help if the F1 key is pressed on
a selected item in the picklist.  <aPickList> may also be
passed as a code-block that returns an array when evaluated.
<aPickList> may be passed as an array of arrays with a
pointer to which sub-array to use as the pick-list via
<nSubList>.  See below.

<nStRow>, <nStCol>, <nEnRow>, <nEnCol> are the screen
coordinates to display the picklist.  If no coordinates
are passed, then the pick-list will be displayed just
to the right of the current GET location.

<lAccept> if .TRUE. will exit the GET if the operator
selects an item from the pick-list.  If .FALSE. (default),
then the value will be returned into the GET and the cursor
will remain in the GET.

<lScanExact> if .TRUE. (default) will scan the <aValues>
array for an "exact" match to the passed value.  IF .FALSE.,
then the standard string-match method will be used.

<lStringList> if .TRUE. will assume that the value in the
GET is a list of characters, and the <aValues> array
contains a single character for each item.  This method is
used to pick one or more items from the the list and add
the item to the value in the GET.  If .FALSE. (default)
then the value of the GET will be replaced by the selected
item.

<nSubList> is used to choose a sub-array from <aValues> if
<aValues> is an array of arrays rather than a single-
dimensional array.  If <nSubList> is a 0 or is not passed
then it is assumed that <aValues> is a single-dimensional
array.

<lAddToGet> if .TRUE. will append the selected value to the
current value(s) in the GET.  If .FALSE. (default), then
the GET contents will be replaced by the selected value.

Notes:

This function will work properly only when used with DC_READMODAL().

If you want an array picklist with multiple columns use DC_READDPICK().

Examples:

 -- Example 1 --

 // Let's say that the only valid entries in the field
 // "nTimeIncr" are 5, 10, 15, 30, and 60.  You would use
 // DC_READAPICK() as follows:

 GetList := {}
 @ 10,10 SAY 'Enter Time Increment ' GET nTimeIncr VALID ;
    DC_READAPICK( nTimeIncr, { 5,10,15,30,60 } ) PICKLIST
 dc_ReadModal( GetList )

 -- Example 2 --

 // Let's say that the only valid entries in the field
 // "nWeek" are 1,2 or 3.  You would use DC_READAPICK() as
 // follows:

 GetList := {}
 @ 10,10 SAY 'Enter Week ' GET nWeek VALID ;
    DC_READAPICK( nWeek, ;
    { { 1,'First' },{ 2,'Second' },{ 3,'Third' } } ) ;
    PICKLIST
 dc_ReadModal( GetList )

 -- Example 3 --

 // You want to choose from a list of single-character
 // options and add each selected option to the GET.

 GetList := {}
 @ 10,10 SAY 'Enter Option List ' GET cList VALID ;
   DC_READAPICK( cList, ;
   { { 'P','Protect' }, {'L','Log'},{'S','Save'} }, ;
   10,40,20,75,,,.t. )

Files:

_DCACHOI.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readdpick()
   dc_achoice()
   dc_dbchoice()


dc_readbox()

Create a modal dialog box and Mouse Buttons for DC_ReadModal()

DC_READBOX() which is used to explode an area of the screen and create an array of mouse buttons to draw on the perimeter of the box and to pass on to DC_ReadModal(). This functions works identical to DC_EXPL() except it also adds the following mouse buttons of the perimeter of the box:<br><br> [þ] - Stuffs ESCape (27 )key [F10:Save] - Stuffs F-10 (-9) key [ESC:Cancel] - Stuffs ESCape (27) key [F1:Help] - Stuffs F-1 (28) key DC_READBOX() also stores the coordinates of the box interior to a static array which is later monitored by DC_GETDEVOUT(), DC_GETDISPLAY(), and DC_READMODAL() to prevent @SAY..GETS from being displayed outside the window region. Such GETS will be added to the Get List but will only be accessible when the Get List is "scrolled" by bumping against the scroll boundaries with a cursor key.

Syntax:

DC_ReadBox ( <nStRow>, ;
             <nEnRow>, ;
             <nStCol>, ;
             <nEnCol>, ;
             [<cTitle>], ;
             @<aActiveArea>, ;
             [<aHotKeys>] ) -> cSaveScreen

Returns:

 A character string that is a "composite" of the coordinates,
 colors, etc. to be used later to restore the screen with
 DC_IMPL().

Arguments:

<nStRow>, <nStCol>, <nEnRow>, <nEnCol> are the active
coordinates of the modal dialogue box.

<cTitle> is the title of the box.

@<aActiveArea> is the name of the variable to store the array
created by DC_READBOX() which will later be passed to
DC_ReadModal().

<aHotKeys> is a multi-dimensional array of hotkeys.  The
information in this array will be used to paint mouse buttons
on the perimeter of the box to pass-on a portion of this
information to DC_ReadModal().  If no array is passed then the
following default array will be created:

<aHotKeys[1]> :

 { {'[Ý]',K_ESC,<nStCol>+2 } }

<aHotKeys[2]> :

 { {'[F10:Save]',K_F10,<nStCol>+2} ;
   {'[ESC:Cancel]',K_ESC,<nStCol>+15},;
   {'[F1:Help]',K_F1,<nStCol>+30}  }

<aHotKeys[1]> is an array of buttons to place on the top of
the dialogue box.

<aHotKeys[2]> is an array of buttons to place on the bottom of
the dialogue box.

Examples:

LOCAL GetList := {}, aReadArea, cSaveScreen

cSaveScreen := DC_READBOX( 10, 10, 19, 70,, @aReadArea )
@ 12,15 say 'Customer Number ' GET cust_nmbr
@ 13,15 say '  Customer Name ' GET cust_name
@ 14,15 say '         Street ' GET street
@ 15,15 say '           City ' GET city
@ 16,15 say '          State ' GET state
@ 17,15 say '            Zip ' GET zip
DC_ReadModal( GetList, 2, aReadArea )

Files:

_DCGETSY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()


dc_readcapfirst()

Capitalize all first letters of all words in all GETs

DC_READCAPFIRST() is used to automatically capitalize the first letter of each new word when typed into all GETs. <br><br> If you wish to CapFirst only a "specified" GET, then use the CAPFIRST command in the @SAY..GET command line and the #include "dcget.ch" statement.<br><br>

Syntax:

DC_ReadCapFirst ( <lMode> ) -> lStatus

Returns:

 A logical value whic is the last setting of the "CapFirst"
 flag.

Arguments:

<lMode> if .TRUE. will set the "CapFirst" flag.  From then
on all GETs read by DC_READMODAL() will automatically
capitalize the first letter of each new word when typed
into a GET.  If .FALSE. will reset the "CapFirst" flag.

Examples:

 -- Example 1 --

 local cCustName, cAddress, GetList:={}
 store cust_name to cCustName
 store address to cAddress
 DC_READCAPFIRST(.t.)
 @ 10,10 say 'Customer Name ' get cCustName
 @ 11,10 say 'Street Address ' get cAddress
 dc_readmodal( GetList )
 DC_READCAPFIRST(.f.)

 -- Example 2 --

 local cCustName, cAddress, GetList:={}
 store cust_name to cCustName
 store address to cAddress
 @ 01,10 say 'Customer Name ' get cCustName CAPFIRST
 @ 11,10 say 'Street Address ' get cAddress
 dc_readmodal( GetList )

Files:

_DCGETSY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()


dc_readclick()

Evaluate code-block if mouse is double-clicked in a GET

DC_READCLICK() is designed to be used in a the VALID clause of a GET statement. This will evaluate a code block only if the mouse left button is double-clicked or the right button is clicked on the specified GET or if (optionally) the last key hit is the <ENTER> key or if (optionally) the value of the GET is empty.<br><br>

Syntax:

DC_ReadClick ( [<xValue>], ;
               <bEval>, ;
               [<lEnter>], ;
               [<lNoEmpty>] ) -> xValue

Returns:

 If the mouse is double-clicked the returns the value
 returned by the evaluated code-block, otherwise returns
 .TRUE.

Arguments:

<xValue> is the value of the GET memory variable. If this
is passed as a NIL, then the oGET:VarGet() value will be
used.

<bEval> is the code block to evaluate if the mouse is
double-clicked.

<lEnter> if .TRUE. will evaluate the code-block if the
ENTER key is hit or the mouse is double-clicked.  If
.FALSE. (default) then only a double-click will invoke
the evaluation.

<lNoEmpty> if .TRUE. will evaluate the code-block if
the <xValue> is empty even if the mouse in not double-
clicked.  The default is .FALSE.

Notes:

This function must be used with DC_READMODAL().

Examples:

 // In this example, the calculator will pop-up and return
 // the accumulator in the <nTax> variable if the mouse
 // is double-clicked on the <nTax> get or the calendar
 // will pop-up and return the selected date if the mouse
 // is double-clicked on the <dDate> get.

 @ 12,10 say 'Sales Tax' get nTax ;
   VALID DC_READCLICK( nTax, { |n| dc_popcalc(n)} )
 @ 13,10 say '     Date' get dDate ;
   VALID DC_READCLICK( dDate, { |d| dc_popdate(d)} )

Files:

_DCGETSY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()


dc_readcolor()

A function for validating color strings in a GET

DC_READCOLOR() is used to validate a color-string value in a GET. DC_READCOLOR() should be used as a VALID function in a GET statement. The pick-list will be displayed whenever the input is not valid or when the mouse is double-clicked.

Syntax:

DC_ReadColor ( <cColor>, ;
               <nDisplayRow>, ;
               [<lEmptyOK>] ) -> lValid

Returns:

 A logical .TRUE. if the color string entered is valid or
 the operator picked a color from the pick-list.

Arguments:

<cColor> is the name of the GET variable.

<nDisplayRow> is the start display row to display the color
pick-list.

<lEmptyOK> if .TRUE. will allow <cColor> to be empty.  If
.FALSE. (default) then if <cColor> is empty the color
pick-list will be automatically displayed.

Notes:

This function will work properly only when used with DC_READMODAL().

Examples:

  @ 7,12 SAY 'Enter a color string' GET cColor ;
    VALID DC_ReadColor( @cColor, 15 ) PICKLIST

Files:

_DCCLRSL.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()


dc_readcua()

Set CUA-Compliance for Navigating Gets

DC_READCUA() is used to set the CUA-Compliant mode for terminating a table of GETS. The normal termination method is CTRL-W or CTRL-END, whereas the CUA-Compliant method of terminating a table of GETS is the ENTER key. In both modes the TAB key will move to the next get and the SHIFT-TAB key will move to the previous get.<br><br> CUA-Compliant mode is consistent with IBM and Windows software systems.

Syntax:

DC_ReadCUA ( [<lNewCUAMode>] ) -> lOldCUAMode

Returns:

 A logical value equivalent to the previous setting.

Arguments:

<lNewCUAMode> if .TRUE. will set the CUA-compliant mode ON,
if .FALSE. will set the CUA-compliant mode OFF, and if not
passed will not affect the current setting.

Examples:

 /* -- Set CUA-compliance ON -- */
 DC_READCUA(.t.)

Files:

_DCGETSY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()
   dc_readalt()
   dc_readnav()


dc_readcut()

Establish the keys to use for cutting and pasting Gets

DC_READCUT() is used to establish the keyboard keys to use for cutting and pasting between GETS when using DC_READMODAL() function.<br><br> The default key for CUT is ALT-G (grab). The default key for PASTE is ALT-R (replace).

Syntax:

DC_ReadCut ( [<aKeys>] ) -> aOldKeys

Returns:

 A 2-element array containing the current keys.

Arguments:

<aKeys> is an array of 2 elements.

Element  Type   Description  Default
-------  ----	  -----------  -----------
   1      N     Cut key      290 (Alt-G)
   2      N     Paste key	275 (Alt-R)

Files:

_DCGETSY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()


dc_readdpick()

Pops up database or array pick-list in a GET

DC_READDPICK() will pop-up a database pick-list or a multi- dimensional array pick-list if the mouse is double-clicked on a GET and return data from the selected record or array element into the GET. DC_READDPICK() should be used as a VALID function in a GET statement.

Syntax:

DC_ReadDPick( <xValue>, ;
              [<cAlias>], ;
              <aOptions>, ;
              <aColumns>, ;
              [<bFieldBlock>], ;
              [<aData>], ;
              [<bPreBlock>], ;
              [<bPostBlock>], ;
              [<lSeek>], ;
              [<lEmptyOK>], ;
              [<cFilter>], ;
              [<nSeekIndex>], ;
              [<xSeekValue>] ) -> lStatus

Returns:

 A logical .TRUE. if the operator clicks on a different GET
 or if the operator chooses and item from the pick-list.  A
 logical .FALSE. if the operator presses the ESCAPE key.

Arguments:

<xValue> is the name of the GET memory variable.

<cAlias> is the alias of the work area to select for the
pick list. This parameter is not needed if <aData> is passed.

<aOptions> is an array of options about the picklist box.
This array must conform to the same requirements as the
<aOptions> array for DC_DBCHCREATE().

<aColumns> is an array of columns to display in the picklist
box.  This array must conform to the same requirements as the
<aColumns> array for DC_DBCHCREATE().

<bFieldBlock> is a code-block to evaluate after the user
chooses the record from the pick-list.  The evaluated output
will be stored in <xValue>.

<aData> is the name of a multi-dimensional array containing
the pick-list data.  If this parameter is not passed, then the
pick-list data will come from the database selected by <cAlias>.

<bPreBlock> is a code block to evaluate before popping up the
pick-list.  <bPostBlock> is a code block to evaluate after the
pick-list box is closed.  These are optional parameters and are
used for such functions as opening and closing the database,
setting filters and or indexes, etc. in the event that the
database is not already open or the database conditions are
unknown.

<lSeek> if .TRUE. (default) will seek to the value passed as
<xSeekValue> if not empty, otherwise will seek to the value
passed as <xValue>.  A .TRUE. will be returned if found,
otherwise a database pick-list will be displayed.

<lEmptyOK> if .TRUE. will return a .TRUE. if <xValue> is empty
and <lSeek> is .FALSE.  The pick-list will not be displayed.

<cFilter> is a filter string to impose upon the database before
seeking or displaying records.  Any old filter will be restored
before returning.

<nSeekIndex> is the number (numeric) or tag-name (character) of
the index to select before seeking the record when <lSeek> is
.TRUE.  If this parameter is not passed, then the currently
selected index will be used.   The currently selected index will
be restored upon return.

<xSeekValue> if not empty, will be used to perform the seek when
<lSeek> is .TRUE., otherwise <xValue> will be used.

Notes:

This function will work properly only when used with DC_READMODAL().

Examples:

 -- Example 1 --

 // In this example a GET table asks the operator for a Customer
 // Number.  If the operator double-clicks on the GET, the
 // CUSTOMER database will be selected, a pick-list will pop-up
 // displaying the CUSTOMER NUMBER and CUSTOMER NAME.  The
 // CUSTOMER NUMBER of the selected record will be returned into
 // the GET variable.

 local cCustomer := SPACE(10), GetList := {}
 @ 10,10 say 'Enter Customer Number ' GET cCustNmbr ;
 VALID DC_READDPICK( cCustNmbr, 'CUSTOMER',  { 5,20,20,75 },;
                    { {{||cust_nmbr},'Number' },;
                      {{||cust_name},'Customer Name' } },;
                    {||PAD(cust_nmbr,10)} )
 dc_readmodal(GetList)

 -- Example 2 --

 // In this example a GET table asks the operator for a File
 // Name.  If the operator double-clicks on the GET, the
 // Directory() function will be used to create an array of
 // file names which will be displayed in the pick-list.  The
 // selected file will be returned into the GET variable.

 local cFileName := space(50), GetList := {}
 @ 10,10 say 'Enter File Name' get cFileName ;
  VALID DC_READDPICK( cFileName,,  { 5,20,20,75 },;
  { { 1,'File Name',15 }, { 2,'Size',8 }, { 3, 'Date',8 }},;
  {|a,n|a:=Directory(),n:=dc_arrayrec(),PAD(a[n,1],50)},;
   Directory() )
 dc_readmodal(GetList)

Files:

_DCDBCHO.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readapick()
   dc_dbchoice()


dc_readempty()

Validate that a GET is not empty or display message

DC_READEMPTY() is used as a VALID function in a GET statement to validate that a field is not empty. If the field is empty, a passed message will be displayed.

Syntax:

DC_ReadEmpty ( <xMemVar>, ;
               { <cLine1>,...<cLineN> } ) -> lStatus

Returns:

 Returns .TRUE. if <xMemVar> is not empty, otherwise will
 display message, wait for a key hit or mouse-click, then return
 .FALSE.

Arguments:

<xMemVar> is the memvar to validate.

<cLine1> thru <cLineN> is an array of character strings.  This is
the message to display if the field is empty.

Examples:

#include 'dcdialog.ch'

PROCEDURE Xtest()

LOCAL GetList := {}, cCustName := Space(30)

@ 10,10 DCSAY 'Enter Customer Name ' GET cCustName ;
   VALID DC_READEMPTY( cCustName , ;
         { "Must enter a Customer Name" } )

DCREAD GUI FIT ADDBUTTONS

RETURN

Files:

_DCGETSY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()


dc_reader()

A Replacement for GetReader() that works with mouse

DC_READER() is a direct replacement for the Clipper GetReader() function and works identical except that it recognizes mouse events and will automatically move the cursor up and down through the gets if the mouse is clicked within an active get.<br><br> DC_READER() is the default reader for DC_READMODAL(). This function may be "inherited" by a custom reader posted as the oGet:reader code block. A custom reader function can perform special actions, such as displaying messages, and then call DC_READER() to continue the "moused" key read action.

Syntax:

DC_Reader ( <oGet>, ;
            <aGetList> ) -> nil

Returns:

 nil

Arguments:

<oGet> is the Get object that is currently in focus.

<aGetList> is the Get List array.

Notes:

DC_READER() should be used only when using DC_READMODAL().

Examples:

LOCAL GetList := {}

@ 13,15 say '  Customer Name ' GET cust_name
@ 14,15 say '         Street ' GET street
@ 15,15 say '           City ' GET city
@ 16,15 say '          State ' GET state
@ 17,15 say '            Zip ' GET zip
oGet := GetList[5]
oGet:reader := {|oGet| MyReader( oGet, GetList )}
dc_readmodal( GetList )
Return nil

// ----------------- //

STATIC FUNCTION MyReader ( oGet, GetList )

@ 24,0 SAY 'Enter a Valid Zip Code'
DC_READER( oGet, GetList )
@ 24,0 clear
Return nil

Files:

_DCGETSY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()


dc_readgets()

Process the Getlist array with the Text or GUI reader

DC_READGETS() is used to process the Text/Gui Getlist array and prepare a GetList that is compatible with DC_READMODAL() and READMODAL() in Text mode or to pass it to DC_READGUI() for a GUI dialogue.<br><br> DC_READGETS() tests the value returned by the DC_GUI() function and if it is .TRUE. processes the GetList with the GUI reader, otherwise it processes the Getlist with the text-reader.<br><br>

Syntax:

DC_ReadGets ( <aGetList>, ;
              [<cTitle>], ;
              [<aActiveArea>], ;
              [<aGetOptions>], ;
              [<bEventHandler>], ;
              [<aRef>], ;
              [<oDialog>], ;
              [<oAppWindow>] ) -> lUpdated

Returns:

 .TRUE. if any gets were updated, .FALSE. otherwise.

Arguments:

<aGetList> is an array containing a list of Get objects to
edit.

<cTitle> is the title to display on the top of the GUI
dialogue box.  This is ignored if painting text-based GETS.

<aActiveArea> is an array of 5 elements defining text-based
coordinates:

 Element   Type  Description
 -------   ----  -----------------------------------------
  [1]       N    Start Row
  [2]       N    Start Column
  [3]       N    End Row
  [4]       N    End Column
  [5]       A    Mouse buttons
                 (See DC_MOUSEKEY() for specification)

In text mode, if no array is passed, then if the mouse is
clicked outside any active GETs, it will do nothing.  If an
array is passed, and the mouse is clicked outside the array
coordinates, the READ will be terminated exactly the same as
hitting the CTRL-W key.

In GUI mode, if this array is passed, then the size of the
dialogue box is calculated by converting the text-based
coordinates to GUI coordinates.  If no array is passed, the
the size of the dialogue box is determined by <GetOptions>.
If no <GetOptions> array is passed, then the dialogue
defaults to 640 x 480.

<aGetOptions> is an array of options for the GUI dialogue
box.  This is ignored if painting text-based GETS.
See DCDIALOG.CH for a description of this array.

<bEventHandler> is a code block which points to a custom
event handler.  DC_ReadGui() uses it's own, default event
handler to manage the objects during the running of the
program.  The default event handler makes a call to the
custom event handler before processing it's default events.
The custom event handler uses Appevent() to get information
on the current event and passes the following parameters:

 1. nEvent   - The event type.
 2. mp1      - The first event parameter.
 3. mp2      - The second event parameter.
 4. oXbp     - A pointer to the object creating the event.
 5. oDlg     - A pointer to the main dialogue object.
 6. aGetlist - A pointer to the GetList array.
 7. aRef     - A pointer to an optional Reference array that
               was passed to DC_ReadGets().

The code block should look like this:

 bEventHandler := {|a,b,c,d,e,f,g,h|MyHandler(a,b,c,d,e,f,g,h)}

<aRef> is any array.  Programming dialogue systems that must
manipulate many variables is much simpler if all the variables
are placed into a single array and then passed to the dialogue
system and its event custom event handler.  See example 2.

@<oDialog> is a reference to a parent dialog or to a memory
variable to store a reference to the dialog that will be created.
If <oDialog> has already been created as an XbpDialog class
object, it will become the parent for all the objects in the
GetList.  If <oDialog> is passed by reference as a NIL, the
dialog object created by the reader will be stored in this
memory variable.

The parent of the dialog that will be created is referenced by
<oAppWindow>.  If no <oAppWindow> is passed then the parent
of the created dialog will be AppDeskTop().

Examples:

  In this example, DC_ReadBox() and DC_Impl() will only
  display and restore the window in Text-Mode.  They are
  ignored in GUI mode.

  #include "dcdialog.ch"

  LOCAL GetList := {}, GetOptions, aReadArea
  DC_Gui(.t.)   // turn on GUI mode
  GetList := {}
  cScrn := DC_ReadBox(3,5,14,75,,@aReadArea)
  @ 5,10 DCSAY ' Last Name' GET cLastName
  @ 5,40 DCSAY 'First Name' GET cFirstName
  @ 7,10 DCSAY '   Company' GET cCompany
  @ 8,10 DCSAY '    Street' GET cStreet
  @ 9,10 DCSAY '      City' GET cCity
  @10,10 DCSAY '     State' GET cState
  @10,40 DCSAY '   Country' GET cCountry
  @12,40 DCSAY '     Phone' GET cPhone PICT '(999)-999-9999'
  DCGETOPTIONS SAYWIDTH 15
  lOk := DC_ReadGets( GetList,"Enter Data",aReadArea,;
                      GetOptions )
  DC_Impl(cScrn)

Files:

_DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()
   dc_readgui()
   DIALOG GETLIST


dc_readgui()

Process the Getlist array with the GUI reader

DC_READGUI() is used to process the Getlist array using the GUI Dialog reader.<br><br> This is the GUI equivalent to DC_ReadModal(). It uses the GetList array of dialogue objects created by the DC* commands in DCDIALOG.CH. <br><br>

Syntax:

DC_ReadGUI ( <aGetList>, ;
            [<cTitle>], ;
            [<aGetOptions>], ;
            [<lnButtons>], ;
            [<bEventHandler>], ;
            [<aRef>], ;
            [@<oDialog>], ;
            [<lFit>], ;
            [<lDesignOn>], ;
            [<lExit>], ;
            [<oAppWindow>], ;
            [<lModal>], ;
            [<bEval>], ;
            [<lEnterExit>],;
            [<oOwner>], ;
            [<xSetFocus>], ;
            [<ancGroup>], ;
            [<anTimeOut>] ) -> lUpdated

Returns:

 .TRUE. if DC_ReadGui() was exited by one of the following
 methods:

 1. DC_ReadGuiEvent(DCGUI_EXIT_OK,GetList)
 2. The user pressed ENTER when the ENTEREXIT clause of DCREAD GUI
    command was used.
 3. The user closed the main dialog window and the CLOSEQUERY
    clause of DCREAD GUI was used.

 .FALSE. if DC_ReadGui() was exited by one of the following
 methods:

 1. DC_ReadGuiEvent(DCGUI_EXIT_ABORT,GetList)
 2. The user pressed ESCAPE.
 3. The user closed the main dialog window and the CLOSEQUERY
    clause of DCREAD GUI was not used.

Arguments:

<aGetList> is an array containing a list of Get objects to edit.

<cTitle> is the title to display on the top of the GUI
dialogue box.

<aGetOptions> is an array of options for the GUI dialogue
box.  This is ignored if painting text-based GETS.
See DCDIALOG.CH for a description of this array.

<lnButtons> will add extra buttons to the bottom area of the main
dialog window.  <lnButtons> may be a numeric value designating the
buttons to add based on the below table. DCDIALOG.CH contains
DCGUI_BUTTON_* constant definitions for the available buttons.
These values are summed to enable multiple buttons.

Numeric Value       Description
------------------  ---------------------------------------------
DCGUI_BUTTON_OK     Will add a button with the caption OK.
                    Selecting this button will exit the GUI reader
                    and save all changes to their associated
                    memory variables.

DCGUI_BUTTON_CANCEL Will add a button with the caption CANCEL.
                    Selecting this button will exit the GUI reader
                    and restore all memory variables to their
                    original value.

DCGUI_BUTTON_EXIT   Same as DCGUI_BUTTON_OK except the caption is
                    labeled as EXIT.

Optionally, <lnButtons> may be a logical .TRUE. This will paint
both the OK and CANCEL buttons.

<bEventHandler> is a code block which points to a custom
event handler.  DC_ReadGui() uses it's own, default event
handler to manage the objects during the running of the
program.  The default event handler makes a call to the
custom event handler before processing it's default events.
The custom event handler uses Appevent() to get information
on the current event and passes the following parameters:

 1. nEvent   - The event type.
 2. mp1      - The first event parameter.
 3. mp2      - The second event parameter.
 4. oXbp     - A pointer to the object creating the event.
 5. oDlg     - A pointer to the main dialogue object.
 6. aGetlist - A pointer to the GetList array.
 7. aRef     - A pointer to an optional Reference array that
               was passed to DC_ReadGui().
 8. lOk      - A logical value that is .TRUE. if the OK button
               was clicked and .FALSE. if CANCEL was clicked.

 The code block should look like this:

 bEventHandler := {|a,b,c,d,e,f,g,h|MyHandler(a,b,c,d,e,f,g,h)}

 The Function should look like this:

 STATIC FUNCTION MyHandler ( nEvent, mp1, mp2, oXbp, oDlg,
                             aGetlist, aRef, lOk )

 /* custom code */

 RETURN DCGUI_NONE

The function must return a numeric value which controls the
behavior of the event loop as follows:

 Return Value          Behavior
 ------------          --------------------------------------------
 DCGUI_NONE            Continue processing the event
 DCGUI_IGNORE          Ignore event
 DCGUI_CLEAR           Ignore event and clear all events from queue
 DCGUI_EXIT_OK         Exit the DC_ReadGui() reader event loop
                       and return a logical .TRUE.
 DCGUI_EXIT_ABORT      Exit the DC_ReadGui() reader event loop,
                       restore all referenced memvar to their
                       original value and return a logical .FALSE.
 DCGUI_MOVE_UP         Set focus to previous object in Get List
 DCGUI_MOVE_DOWN       Set focus to next object in Get List
 DCGUI_MOVE_TOP        Set focus to first object in Get List
 DCGUI_MOVE_BOTTOM     Set focus to last object in Get List
 DCGUI_MOVE_UP_PAR     Set focus to previous object in Get List that
                       has the same parent as the current object.
 DCGUI_MOVE_DOWN_PAR   Set focus to next object in Get List that
                       has the same parent as the current object.
 DCGUI_MOVE_TOP_PAR    Set focus to first object in Get List that
                       has the same parent as the current object.
 DCGUI_MOVE_BOTTOM_PAR Set focus to last object in Get List that
                       has the same parent as the current object.
 DCGUI_NOHOTKEY        Don't activate hot key associated with
                       the current object.

<aRef> is any array.  Programming dialogue systems that must
manipulate many variables is much simpler if all the variables
are placed into a single array and then passed to the dialogue
system and its event handler.  See example 2.

@<oDialog> is a reference to a parent dialog or to a memory
variable to store a reference to the dialog that will be created.
If <oDialog> has already been created as an XbpDialog class
object, it will become the parent for all the objects in the
GetList.  If <oDialog> is passed by reference as a NIL, the
dialog object created by the reader will be stored in this
memory variable.

The parent of the dialog that will be created is referenced by
<oAppWindow>.  If no <oAppWindow> is passed then the parent
of the created dialog will be AppDeskTop().

<lFit> if .TRUE. will automatically form the dialog screen to
fit comfortably around the objects within the dialog.  This
option allows the programmer to use coordinates on dialog
objects for relative addressing only without worrying about how
the objects relate to the borders of the main dialog.  After
all the objects are created, the main dialog borders will be
sized to fit the objects.  The default is .FALSE.

<lDesignOn> will add a button to the bottom of the dialog to
click on for enabling DESIGN mode.  In design mode, objects may
be resized or moved with the mouse and the new sizes and
coordinates are written back to the GetList array.  This
feature is useful for writing data-driven dialog systems.

<lExit> if .TRUE. will exit the reader after the objects
are created and not enter the reader's event loop.  It is the
responsibility of the programmer to insure that events are
managed and the dialog is destroyed.  This feature is used to
add more objects to an existing dialog, or to create a dialog
that will be managed by an external event loop.

<oAppWindow> is the parent object for the main dialog.  If this
argument is not passed, then the AppDeskTop() will be used.

<lModal> if .TRUE. will set this dialog modal state to MODAL -
APPLICATION WIDE. If .FALSE. the dialog will be NONMODAL.  The
default is .FALSE.

<bEval> is an optional code block to evaluate after all the
objects are created and just before entering the event loop.
The main dialog object is passed to this code block as an
argument.

<lEnterExit> if .TRUE. will exit the dialog if the ENTER key is
pressed in the "last GET".  If .FALSE. (default), then pressing
the ENTER key in the last GET will cause the first GET to receive
focus.

<oOwner> is the owner of the dialog window.

<lArrayTranslate> if .TRUE. will translate the HEIGHT, WIDTH,
START COLUMN and START ROW elements in the GETLIST array to
pixel coordinates and write these coordinates back to the
original GETLIST array.  It will also write the translated
Dialog window coordinates to the GETOPTIONS array and set the
TRANSLATE flag in the GETOPTIONS array to .FALSE.

<xSetFocus> is the object that receives focus when entering
the event handler. <xSetFocus> may be a type "O" (object), a type
"N" (numeric) or a type "C" character.  If <xSetFocus> is a type
"N" then the numeric value must be a number from 1 to the length
of <aGetList>.  This is an ordinal pointer to the GetList item.
If <xSetFocus> is a type "C" then the character string value must
be a value equivalent to the ID of the item in the GetList which
is to receive focus.

<ancGroup> is the GetList group to create.  Each item in the
GetList may be assigned a group name or number via the
GROUP <ancGroup> clause.  If a numeric or character value is
passed then only the items in the GetList which match <ancGroup>
will be created.  <ancGroup> may consist of an array of numeric
values or character values so that more than one group may be
created. If <ancGroup> is a nil then all items in the GetList
will be refreshed.

<anTimeOut> is used to exit the dialog after a specified
number of seconds.  <anTimeOut> may be a numeric value equivalent
to the number of seconds or an array of two elements as defined
below:

 ELEMENT  TYPE  DESCRIPTION
 -------  ----  ------------------------------------------------
    1       N   The timeout in seconds
    2       B   A code block to execute after the timeout.  The
                code block must return a logical value.  If a .T.
                is returned the exit will occur, otherwise the
                timeout will be reset.

Notes:

Examples:

/*
This example will display a list of fields in the
"Available Fields" selection, allow the operator to
select a set of fields, then display a Browse of the
database for the fields selected.  The example shows
how to use DC_READGUI() to create a master dialog and
a sub dialog.
*/

#include "dcpick.ch"

PROCEDURE XTest( )

LOCAL GetList := {}, GetOptions, cAlias, aListField, ;
      aPickField, oBrowse, oDialog

USE COLLECT NEW SHARED

cAlias := 'COLLECT'
aListField := Array(FCount())
AFields(aListField)

@ 2,3 DCPICKLIST aPickField LIST aListField ;
   CAPTION "Available Fields", "Selected Fields" ;
   SIZE 35,12 ;
   DATALINK {||BrowseCollect(cAlias,oDialog,@oBrowse,@aPickField)}

DCGETOPTIONS ;
   WINDOW HEIGHT 360 ;
   WINDOW WIDTH 600

DC_READGUI(GetList, "Picklist Demo", GetOptions, .t., nil, nil, @oDialog )

RETURN

/* --------------------- */

STATIC FUNCTION BrowseCollect ( cAlias, oDialog, oBrowse, aPickField )

LOCAL GetList := {}, i, aChildList

IF Valtype(oBrowse) = 'O'
  aChildList := oBrowse:ChildList()
  FOR i := 1 TO Len(aChildList)
    aChildList[i]:Destroy()
  NEXT
  oBrowse:Destroy()
ENDIF

oBrowse := nil

IF Empty(aPickField)
  RETURN nil
ENDIF

@ 2,40 DCBROWSE oBrowse DATA cAlias SIZE 39,12 PARENT oDialog:drawingArea

SELECT collect
FOR i := 1 TO Len(aPickField)
  DCBROWSECOL DATA &('{||COLLECT->'+aPickField[i]+'}') ;
    HEADER aPickField[i] PARENT oBrowse
NEXT

DC_READGUI( GetList, nil, nil, .f., nil, nil, oDialog )

oBrowse:hide()
oBrowse:show()

RETURN nil

Files:

_DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   DCREAD GUI
   dc_readgets()
   DIALOG GETLIST
   dc_getrefresh()


dc_readguidebug()

Enable/Disable DEBUG mode in the GUI reader

DC_READGUIDEBUG() is used to turn on debugging information for DC_READGUI(). When debug mode is ON, information about the type of Getlist object is echoed to a CRT window while the objects are being created by DC_READGUI(). This is handy when an error occurs in the DC_READGUI() due incorrect arguments in the GetList array passed to the function. The last line of information in the CRT window will contain information to help determine which GET caused the error.<br><br> Debug mode may also echo the "define" name of all events that occur while in the event loop to see the order in which events occur when using the mouse or keyboard.

Syntax:

DC_ReadGuiDebug ( [<nDebug>] ) -> nStatus

Arguments:

<nDebug>, is a numeric value which determines the level of
debugging required.  DCDIALOG.CH contains a set of defines
starting with DCGUI_DEBUG_*.  The numeric values from the below
table are summed together to enable desired debugging features.

  Constant            Description
 -------------------  -------------------------------------------
 DCGUI_DEBUG_CREATE   Display debugging information while creating
                      objects.

 DCGUI_DEBUG_EVENTS   Display debugging information about events
                      in the event loop.

 DCGUI_DEBUG_VALIDATE Display debugging information during
                      Validation routine.

Examples:

  #include "dcdialog.ch"

  PROCEDURE Xtest()

  LOCAL GetList := {}, GetOptions, cOption, oMyGroup

  cOption := 'P'

  @ 4,10 DCGROUP oMyGroup CAPTION "Select an Operation" ;
    SIZE 40,8

  @ 1,2 DCRADIO cOption PROMPT 'Save to Dictionary' VALUE 'D' ;
        PARENT oMyGroup

  @ 2,2 DCRADIO cOption PROMPT 'Save to Source Code' VALUE 'S' ;
        PARENT oMyGroup

  @ 3,2 DCRADIO cOption PROMPT 'Make a Backup file' VALUE 'B' ;
        PARENT oMyGroup

  @ 4,2 DCRADIO cOption PROMPT 'Pack the File' VALUE 'P' ;
        PARENT oMyGroup

  DC_READGUIDEBUG( DCGUI_DEBUG_CREATE + DCGUI_DEBUG_EVENTS )

  DCREAD GUI ;
    TITLE 'My Dialogue' ;
    FIT ;
    ADDBUTTONS

  RETURN

Files:

_DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readgui()
   dc_appeventdefine()
   dc_getlisttype()
   dc_qout()


dc_readguieval()

Post a code block for later evaluating in DC_ReadGui()

DC_ReadGuiEval() is a Get-Set function that is used to post a code block to be evaluated just before starting up the event loop in DC_ReadGui(). The dialog object created by DC_ReadGui() is passed to this code block. Use this function when it is necessary to call the same piece of code every time a DC_ReadGui() is called. <br><br>

Syntax:

DC_ReadGuiEval ( [<bEval>] ) -> bOldEval

Returns:

The previously stored codeblock.

Arguments:

<bEval> is the code block to evaluate.

Notes:

Examples:

/*
This will call DoSomething() every time the dialog window
receives input focus.
*/

DC_READGUIEVAL( {|o|o:setInputFocus := {||DoSomething()} } )

Files:

_DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readgui()


dc_readguievent()

Create an event to control the GUI reader

DC_ReadGuiEvent() is used to control behavior of the DC_ReadGui() function. This function can be used to exit DC_ReadGui() or to specify navigation methods.<br><br> The navigation modes take into consideration any WHEN clause and HIDE clause that is attached to objects and skips past those objects which are disabled or hidden.

Syntax:

DC_ReadGuiEvent( <nEvent>, ;
                 <GetList> ) -> lStatus

Returns:

 A logical .TRUE. if a new object was placed into focus, otherwise
 a logical .FALSE.

Arguments:

<nEvent> is a numeric value equivalent to one of the defined
values in the below table.  These definitions exist in
DCDIALOG.CH.

   <nEvent>             Behavior
  ------------          --------------------------------------------
  DCGUI_CLEAR           Clear all events from queue
  DCGUI_EXIT_OK         Exit the DC_ReadGui() reader event loop
                        and return a logical .TRUE.
  DCGUI_EXIT_ABORT      Exit the DC_ReadGui() reader event loop,
                        restore all referenced memvar to their
                        original value and return a logical .FALSE.
  DCGUI_MOVE_UP         Set focus to previous object in Get List
  DCGUI_MOVE_DOWN       Set focus to next object in Get List
  DCGUI_MOVE_TOP        Set focus to first object in Get List
  DCGUI_MOVE_BOTTOM     Set focus to last object in Get List
  DCGUI_MOVE_UP_PAR     Set focus to previous object in Get List that
                        has the same parent as the current object.
  DCGUI_MOVE_DOWN_PAR   Set focus to next object in Get List that
                        has the same parent as the current object.
  DCGUI_MOVE_TOP_PAR    Set focus to first object in Get List that
                        has the same parent as the current object.
  DCGUI_MOVE_BOTTOM_PAR Set focus to last object in Get List that
                        has the same parent as the current object.

<GetList> is the array containing the Get List.

Examples:

#include 'dcdialog.ch'

 PROCEDURE Xtest()

 LOCAL GetList := {}, cDesc, cType, cSubType, cLocation, cComments, ;
       oToolBar, GetOptions

 USE COLLECT NEW

 cDesc := COLLECT->descrip
 cType := COLLECT->type
 cSubType := COLLECT->sub_type
 cLocation := COLLECT->location
 cComments := COLLECT->comments

 @ 5,1 DCSAY 'Description' GET cDesc
 @ 6,1 DCSAY '       Type' GET cType
 @ 7,1 DCSAY '   Sub-Type' GET cSubType
 @ 8,1 DCSAY '   Location' GET cLocation
 @ 9,1 DCSAY '   Comments' GET cComments

 DCTOOLBAR oToolBar

 DCADDBUTTON CAPTION 'First Field' SIZE 10 PARENT oToolBar ;
    ACTION {||DC_ReadGuiEvent(DCGUI_MOVE_TOP_PAR,GetList)}

 DCADDBUTTON CAPTION 'Next Field' SIZE 10 PARENT oToolBar ;
    ACTION {||DC_ReadGuiEvent(DCGUI_MOVE_DOWN_PAR,GetList)}

 DCADDBUTTON CAPTION 'Previous Field' SIZE 10 PARENT oToolBar ;
    ACTION {||DC_ReadGuiEvent(DCGUI_MOVE_UP_PAR,GetList)}

 DCADDBUTTON CAPTION 'Last Field' SIZE 10 PARENT oToolBar ;
    ACTION {||DC_ReadGuiEvent(DCGUI_MOVE_BOTTOM_PAR,GetList)}

 DCADDBUTTON CAPTION 'Save' SIZE 10 PARENT oToolBar ;
    ACTION {||DC_ReadGuiEvent(DCGUI_EXIT_OK,GetList)}

 DCADDBUTTON CAPTION 'Abort' SIZE 10 PARENT oToolBar ;
    ACTION {||DC_ReadGuiEvent(DCGUI_EXIT_ABORT,GetList)}

 DCGETOPTIONS   ;
   WINDOW HEIGHT 300 ;
   WINDOW WIDTH 500

 DCREAD GUI OPTIONS GetOptions

 RETURN

Files:

_DCGETBX.PRG, DCLIPX.LIB

See Also:

   dc_readgui()
   dc_readguieventloop()


dc_readguieventloop()

Start up an event loop that is compatible with GetList

DC_ReadGuiEventLoop() is the main event loop called by DC_ReadGui(). After all the objects are created on the screen by passing a GetList to DC_ReadGui(), a pointer to the GetList is passed to DC_ReadGuiEventLoop() and the event loop remains running until it is exited by a call to DC_ReadGuiEvent() or with the ESCAPE key (if enabled).<br><br> This is a special event handler designed to handle all events and also the following procedures:<br><br> 1. WHEN and HIDE clauses associated with DC* commands are evaluated by a call to DC_GetWhen() in the event loop whenever a xbeP_KillInputFocus event is received. This insures that objects are disabled, enabled, hidden or shown when conditions change that affect their respective code blocks.<br><br> 2. VALID clauses associated with DC* commands are evaluated when an object loses focus and the focus is forced back to the object if the VALID code block returns a .FALSE.<br><br> 3. Keyboard events that are used for navigation through a table of GETs are handled in the event loop. Keys such as ENTER, UP, DOWN, TAB, etc will set focus to the next or previous object while respecting whether or not the object is enabled, unprotected, etc.<br><br> 4. EDITPROTECT clauses associated with DC* commands are evaluated when an object tries to receive focus. If the object is protected by an EDITPROTECT code block (returns .TRUE.) then it will not receive focus.<br><br> 5. Messages are handled in the event loop. An xbeP_SetInputFocus event will test for a MESSAGE clause associated with an object and display the message in the message receptable object established by the MESSAGE INTO clause of DCGETOPTIONS.<br><br> 6. A ToolTip management thread is started in the event loop. This thread displays tooltips associated with an object by the TOOLTIP clause of DC* commands when the mouse is placed over the object.<br><br> 7. Help requests are handled in the event loop. xbeP_HelpRequest events are usually created by pressing F1, however they can be also be created by special programming. Help request events cause the associated help code established by the HELPCODE clause of DC* commands to be passed on to the XbpHelp() object or to a special code block, depending on the HELP options setup in the DCGETOPTIONS command.<br><br> 8. Hot Keys and Accelerator keys are handled in the event loop. When a keyboard event is received it is tested to see if it exists in the GetList and its associated code block is evaluated or it's associated object receives focus and is activated.<br><br> 9. An Event Spy is managed in the event loop. The DC_ReadGuiDebug() function is used to enable Event Spy. This will load EVENTSPY.DLL and pass on all events that are pulled from the event queue to the Event Spy window to watch events that are occurring in the application.<br><brᡂ. The Hot Key for the POPUP clause of @..DCSAY..GET objects is handled in the event loop. The key established by the DC_SetPopKey() function will activate any associated popup codeblock when the GET has focus.<br><brᡃ. The Dot-Prompt Window is called in the event loop. DC_DotHotKey() establishes the key to use to invoke a Dot Prompt. This will load DCLIP1.DLL, which contains the DC_Dot() function, and run an instance of DC_Dot() in a non-modal window and then return to the event loop.<br><brᡄ. DESIGN MODE is handled in the event loop. When the DESIGN hotkey (set by DCGETOPTIONS) event is received, a window will be displayed that gives the user some design options. After selecting the options, the application is placed into "DESIGN MODE". This disables normal events and instead captures mouse events to by used for dragging, moving and/or sizing objects, then saving the new coordinates to the GetList and/or source code.<br><brᡅ. DATATOOLTIPS are handled in the event loop. Mouse motion events associated with DCBROWSE commands will pass information to the ToolTip thread to evaluate data-tooltip codeblocks. See the DATATOOLTIP clause of the DCBROWSE comand.<br><brᡆ. A custom event handler is called in the event loop. The HANDLER clause of DC_ReadGuiEventLoop() is used to set a code block for calling a custom event handler. This allows any event to be intercepted and acted upon by the programmer before it is acted upon by the standard event loop.<br><br>

Syntax:

DC_ReadGuiEventLoop( <aGetList>, ;
                     [<bEventHandler>], ;
                     [@<nEvent>], ;
                     <oParentDlg>, ;
                     [<aRef>], ;
                     [<anTimeOut>], ;
                     [<nWait>], ;
                     [<lMultiLists> ) -> lOkStatus

Returns:

 .TRUE. if DC_ReadGuiEventLoop() was exited by one of the following
 methods:

 1. DC_ReadGuiEvent(DCGUI_EXIT_OK,GetList)
 2. The user pressed ENTER when the ENTEREXIT clause of DCREAD GUI
    command was used.
 3. The user closed the main dialog window and the CLOSEQUERY
    clause of DCREAD GUI was used.

 .FALSE. if DC_ReadGui() was exited by one of the following
 methods:

 1. DC_ReadGuiEvent(DCGUI_EXIT_ABORT,GetList)
 2. The user pressed ESCAPE.
 3. The user closed the main dialog window and the CLOSEQUERY
    clause of DCREAD GUI was not used.

Arguments:

<aGetList> is a GetList that was previously used to create a
set of objects with DC_ReadGui().

<bEventHandler> is a code block which points to a custom
event handler.  DC_ReadGuiEventLoop() makes a call to the
custom event handler before processing it's default events.
The main event handler uses Appevent() to get information
on the current event and passes the following parameters:

 1. nEvent   - The event type.
 2. mp1      - The first event parameter.
 3. mp2      - The second event parameter.
 4. oXbp     - A pointer to the object creating the event.
 5. oDlg     - A pointer to the main dialogue object.
 6. aGetlist - A pointer to the GetList array.
 7. aRef     - A pointer to an optional Reference array that
               was passed to DC_ReadGuiEventLoop().
 8. lOk      - A logical value that is .TRUE. if the OK button
               was clicked and .FALSE. if CANCEL was clicked.

 The code block should look like this:

 bEventHandler := {|a,b,c,d,e,f,g,h|MyHandler(a,b,c,d,e,f,g,h)}

@<nEvent> is a variable, passed by reference, to store the
numerical value of the last event processed in the event loop
before exiting.

<oParentDlg> is the parent dialog window that was either created
by DC_ReadGui() or passed to DC_ReadGui().

<aRef> is an optional array to pass to the custom event handler.

<anTimeOut> is used to exit the dialog after a specified
number of seconds.  <anTimeOut> may be a numeric value equivalent
to the number of seconds or an array of two elements as defined
below:

 ELEMENT  TYPE  DESCRIPTION
 -------  ----  ------------------------------------------------
    1       N   The timeout in seconds
    2       B   A code block to execute after the timeout.  The
                code block must return a logical value.  If a .T.
                is returned the exit will occur, otherwise the
                timeout will be reset.

<nWait> is an optional numerical value that is passed to the
function AppEvent() which pulls events from the event queue.  The
default is 0, meaning that AppEvent() will wait forever for an
event, otherwise it will wait <nWait> seconds.

<lMultiLists> if .TRUE. causes the event handler to support multiple
GetLists.  For example, if an event occurs that is associated
with an object that was created from a child or subsequent
GetList, then all other references to that GetList will be used
when the object is refreshed.  This means that multiple MDI child
windows may now be created using DCREAD GUI and they no longer
need to be running in another thread to maintain multiple event
loops.  Simply use the EXIT clause of DCREAD GUI when creating an
MDI child window to return control to the main event loop.
Running MDI child windows in separate threads is not always
desirable, especially when MDI child windows may need to share
the same workspace, as in the DC_Dbu() utility program.

Examples:

/* This example shows how to create a GUI memo window
   that pops up by pressing ALT_M when in a table
   of text-based Gets. */

PROCEDURE Xtest()

LOCAL GetList := {}, cMemo := '', GetOptions, oDlg, oMemo, oCrt

DC_SetKeyActive(.t.)
@ 0,0 DCMULTILINE cMemo SIZE 50,15 OBJECT oMemo

@17,0 DCPUSHBUTTON CAPTION 'Hide' SIZE 9,1.2  ;
      ACTION {||oDlg:Hide(),DC_ReadGuiEvent(DCGUI_EXIT_OK,GetList), ;
                SetAppFocus(oCrt)}

DCGETOPTIONS HIDE
DCREAD GUI FIT PARENT @oDlg OPTIONS GetOptions EXIT SAVE ;
       TITLE 'Memo Editor.  Press ALT-M to Hide'

SetKey(K_ALT_M, {|x|DC_ClearEvents(), ;
                    x:=oDlg:IsVisible(), ;
                    IIF(x,oDlg:hide(),oDlg:show()),  ;
                    IIF(x,SetAppFocus(oCrt),SetAppFocus(oMemo)),;
                    IIF(x,DC_ReadGuiEvent(DCGUI_EXIT_OK,GetList), ;
                          DC_ReadGuiEventLoop(GetList,,,oDlg)) } )

_ReadGets( @oCrt )
oDlg:Destroy()
SetKey(K_ALT_M,nil)

RETURN

* --------------

PROCEDURE _ReadGets( oCrt )

LOCAL GetList := {}, cName := Space(20), cCity := Space(20), ;
      cState := Space(5), cStreet := Space(30), oAppWindow

oAppWindow := SetAppWindow()
oCrt := XbpCrt():new()
oCrt:create()
SetAppWindow(oCrt)
CLS
SET CURSOR ON
@ 1,1 SAY 'Press ALT-M to toggle display of Memo Editor'
@ 3,1 SAY '  Name' GET cName
@ 4,1 SAY 'Street' GET cStreet
@ 5,1 SAY '  City' GET cCity
@ 6,1 SAY ' State' GET cState
READ
SetAppWindow(oAppWindow)
oCrt:Destroy()

RETURN

Files:

_DCGETBX.PRG, DCLIPX.LIB

See Also:

   dc_readgui()


dc_readguihandler()

Post a "default" event handler for DC_ReadGui()

DC_ReadGuiHandler() is a "Get-Set" function that is used to post a "default" event handler to be used with all DC_ReadGui() dialogs. This function is handy for:<br><br>a. Calling UDFs that write Event transactions to an event log. For example, an EVENT.DBF could contain information about user activity for helping with debugging of obscure problems.<br><br>b. Calling UDFs that display a HELP screen when a new object receives focus or when an action occurs. For example, the user could select "learn mode". xbeP_Activate events on pushbuttons or xbeP_setInputFocus events could automatically display information about this activity in a help window.<br><br>

Syntax:

DC_ReadGuiHandler( [<bHandler>] ) -> bOldHandler

Arguments:

<bHandler> is a code block to evaluate every time an event occurs
in DC_ReadGuiEventLoop().

The DC_ReadGuiEventLoop() event handler makes a call to the
custom event handler before processing it's default events.
The custom event handler uses Appevent() to get information
on the current event and passes the following parameters:

 1. nEvent   - The event type.
 2. mp1      - The first event parameter.
 3. mp2      - The second event parameter.
 4. oXbp     - A pointer to the object creating the event.
 5. oDlg     - A pointer to the main dialogue object.
 6. aGetlist - A pointer to the GetList array.
 7. aRef     - A pointer to an optional Reference array that
               was passed to DC_ReadGets().
 8. lOk      - A logical value that is .TRUE. if the OK button
               was clicked and .FALSE. if CANCEL was clicked.

 The Function should look like this:

 STATIC FUNCTION MyHandler ( nEvent, mp1, mp2, oXbp, oDlg,
                             aGetlist, aRef, lOk )

 /* custom code */

 RETURN DCGUI_NONE

The function must return a numeric value which controls the
behavior of the event loop as follows:

 Return Value          Behavior
 ------------          --------------------------------------------
 DCGUI_NONE            Continue processing the event
 DCGUI_IGNORE          Ignore event
 DCGUI_CLEAR           Ignore event and clear all events from queue
 DCGUI_EXIT            Exit the DC_ReadGui() reader event loop
 DCGUI_MOVE_UP         Set focus to previous object in Get List
 DCGUI_MOVE_DOWN       Set focus to next object in Get List
 DCGUI_MOVE_TOP        Set focus to first object in Get List
 DCGUI_MOVE_BOTTOM     Set focus to last object in Get List
 DCGUI_MOVE_UP_PAR     Set focus to previous object in Get List that
                       has the same parent as the current object.
 DCGUI_MOVE_DOWN_PAR   Set focus to next object in Get List that
                       has the same parent as the current object.
 DCGUI_MOVE_TOP_PAR    Set focus to first object in Get List that
                       has the same parent as the current object.
 DCGUI_MOVE_BOTTOM_PAR Set focus to last object in Get List that
                       has the same parent as the current object.
 DCGUI_NOHOTKEY        Don't activate hot key associated with
                       the current object.

Examples:

DC_ReadGuiHandler( {|a,b,c,d|Transaction(a,b,c,d)} )

STATIC FUNCTION Transaction( nEvent, mp1, mp2, oXbp )

//Record all button activate transactions
IF nEvent == xbeP_Activate
  RecordEvent( nEvent, mp1, mp2, oXbp:caption, ;
               DC_GetCodeBlockText(oXbp:activate) )
ENDIF

RETURN DCGUI_NONE

* ------------

STATIC FUNCTION RecordEvent( nEvent, mp1, mp2, cDesc1, cDesc2 )

LOCAL nSaveArea := Select()

USE EVENTS new

APPEND BLANK

REPL EVENTS->event with nEvent,;
     EVENTS->mp1 with DC_XtoC(mp1), ;
     EVENTS->mp2 with DC_Xtoc(mp2), ;
     EVENTS->desc1 with cDesc1, ;
     EVENTS->desc2 with cDesc2

CLOSE

SELE (nSaveArea)

RETURN nil

Files:

_dcgetbx.prg, DCLIPX.DLL

See Also:

   dc_readgui()
   dc_readguieventloop()


dc_readguilastkey()

Process the Getlist array with the GUI reader

DC_ReadGuiLastKey() is used to retrieve the Last Key that was pressed in a DC_ReadGuiEventLoop().<br><br>

Syntax:

DC_ReadGUILastKey ( <aGetList> ) -> nLastKey

Returns:

The numeric value of the last key that was pressed.

Arguments:

<aGetList> is an array containing a list of Get objects that
was passed to DC_ReadGui() or DC_ReadGuiEventLoop().

Examples:

FUNCTION Xtest()

LOCAL GetList := {}, cSomething := Space(20)

@ 1,1 DCSAY 'Enter something' GET cSomeThing ;
  VALID {||Keytest(GetList)}

DCREAD GUI FIT

RETURN nil

* ------------

STATIC FUNCTION KeyTest( GetList )

DCQQDEBUG DC_ReadGuiLastKey( GetList )

RETURN .t.

Files:

_DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readgui()
   DCREAD
   dc_readguieventloop()


dc_readguimenuaccess()

Assign a set of keys to open menu or tree locks

DC_ReadGuiMenuAccess() is used to establish a set of user keys which are used to access locks that have been placed on menu items which were created by the DCSUBMENU and DCMENUITEM commands or on tree items which were created by the DCTREEITEM command. A user may own keys for individual locks or master keys for a set of locks.<br><br> In a typical application, a user would log on and his/her user record would contain a comma-delimited list of keys for this user. This list would then be passed to DC_ReadGuiMenuAccess().

Syntax:

 DC_ReadGuiMenuAccess( [<cKeyList>] ) -> cKeyList

Returns:

 The currently stored, comma delimited key list.

Arguments:

<cKeyList> is a comma delimited string containing substrings up
to 5 characters in length.

 Example: "ABC,DEF,XY,B*,CX*'

 In this example, the user would have access to the following
 menu and tree items:

 1. Any item that does not have a lock.
 2. Any item that has lock ABC.
 3. Any item that has lock DEF.
 4. Any item that has lock XY.
 5. Any item that has a lock starting with B.
 6. Any item that has a lock starting with CX.

 Programmers should be given the key '*****' to gain access to
 all menu and tree items at all times.

Files:

_DCGETBX.PRG, DCLIPX.DLL

See Also:

   DCSUBMENU
   DCMENUITEM
   DCTREEITEM


dc_readguitypeahead()

Enable Keyboard typeahead buffer in GUI dialogs

DC_ReadGuiTypeAhead() is a Get-Set function that is used to set "typeahead" mode for GUI dialogs.<br><br>When "typeahead" mode is enabled, keys pressed before a dialog is created will be forwarded to the GUI object that first receives focus.

Syntax:

DC_ReadGuiTypeAhead( [<lTypeAhead>] ) -> lOldTypeAhead

Returns:

The previous setting.

Arguments:

<lTypeAhead> if .TRUE. will set "typeahead" mode ON, otherwise
if .FALSE. it will set "typeahead" mode OFF.

Files:

_DCGETBX.PRG


dc_readhelp()

Post a code-block for F1 help when using DC_ReadGets()

DC_READHELP() is used to establish the help procedure to call when the F1 key is pressed or the mouse is clicked on the HELP button that has been displayed when using DC_ReadGets(). If no code block has been posted and the function DC_HELPF1() has been linked into the application then this will automatically default to calling DC_HELPF1().<br><br>

Syntax:

DC_ReadHelp ( [<bHelp>] ) -> bHelp

Returns:

 The last posted code block.

Arguments:

<bHelp> is a code block that is used to call a HELP procedure
when F1 is pressed or the mouse is clicked on HELP.

Examples:

 LOCAL bHelp, bSaveHelp, aReadArea, GetList := {}
 LOCAL cFileName := SPACE(40), cText := SPACE(30)
 bHelp := { |p,l,v| MyF1Help(p,l,v) }
 bSaveHelp := DC_READHELP( bHelp )
 DC_ReadBox( 11,10,17,70,,@aReadArea)
 @ 13,12 SAY ' File Name' GET cFileName
 @ 15,12 SAY 'Enter Text' GET cText
 DC_ReadModal( GetList,,aReadArea )
 DC_READHELP( bSaveHelp )

Files:

_DCGETSY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()


dc_readhtml()

Read the DIALOG GetList with the HTML reader

DC_ReadHtml() is used to process the Getlist array using the GUI HTML reader.<br><br> This is the equivalent to DCREAD HTML. It uses the GetList array of dialogue definitions created by the DC* commands in DCDIALOG.CH and DCHTML.CH. <br><br> An array of DIALOG definitions must exist when using this command and it must have the variable name GETLIST.<br><br>

Syntax:

DC_ReadHtml( <aGetList>, ;
             [<cTitle>], ;
             [<oParent>], ;
             [<cRootDir>], ;
             [<oHtml>], ;
             [<cMessageInto>], ;
             [<cTarget>] ) -> cHtml

Returns:

A character string containing the HTML source code.

Arguments:

<aGetList> is the GetList array.

<cTitle> is the title to display on the top of the
browser window.

<oParent> is any parent DC_Html*() object previously
created by DCREAD HTML.

<cRootDir> is the root directory where other HTML
documents or images reference in the HTML code exist.

@<oHtml> is the name of a variable, passed by reference,
to store a pointer to the DC_HtmlMain() object created by the
HTML reader.  This object can be stored to a static variable
or state management cargo system to maintain the state of the
application.

<cMessageInto> is the name of a variable that will be passed
in a <a href> tag with the message text of any object that uses
the message clause.  This is activated when the user clicks on
the underlined screen prompt.

<cTarget> is the name of the Web Browser frame to invoke the
message call.  If this argument is not used, then a new
browser window will be displayed.

variable.

Files:

_DCHTML.PRG

See Also:

   DCREAD HTML


dc_readincr()

A "VALID" function for incrementing a GET value with the mous

DC_READINCR() is used to increment the value in a GET based on a passed array. DC_READINCR() should be used in a VALID statement to increment through an array of values when the mouse is double-clicked or the right mouse button is pressed.

Syntax:

DC_ReadIncr ( @<getvar>, ;
              <aValues> ) -> .t.

Returns:

 .TRUE.

Arguments:

@<getvar> is the name of the GET variable.

<aValues> is an array of valid values for <getvar>.

Notes:

This function will work properly only when used with DC_READMODAL().

Examples:

 // Let's say that the only valid entries in the field
 // "nTimeIncr" are 5, 10, 15, 30, and 60.  You would use
 // DC_READINCR() as follows:

 GetList := {}
 @ 10,10 SAY 'Enter Time Increment ' GET nTimeIncr VALID ;
    DC_READINCR( @nTimeIncr, { 5,10,15,30,60 } ) .AND. ;
    ' '+STR(nTimeIncr,2)+' ' $ '  5 10 15 30 60 ' PICKLIST
 dc_readmodal( Getlist )

 // If the current value of nTimeIncr is 15, then double-
 // clicking on the get will change it to 30.

Files:

_DCGETSY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()


dc_readkill()

Return, and/or set, whether current READ should be exited

DC_READKILL() is a Get system function that lets you control whether or not to terminate the current READ.<br><br> Unless directly manipulated, DC_READKILL() returns true (.T.) after you issue a CLEAR GETS, the current READ and otherwise returns false (.F.).<br><br> By accessing the function directly, however, you can control the DC_READKILL() flag with its function argument and use it to create new READ Layers.

Syntax:

DC_ReadKill ( <lReadKill> ) -> nil

Returns:

 NIL

Arguments:

<lReadKill> sets the DC_READKILL() flag.  A value of true (.T.)
indicates that the current read should be terminated, and a value
of false (.F.) indicates that it should not.

Notes:

DC_READKILL() works with DC_READMODAL() in the same way that Clipper's READKILL() works with READMODAL().

Files:

_DCGETSY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()


dc_readmodal()

A moused and robust replacement for ReadModal()

DC_READMODAL() is a direct replacement for the Clipper ReadModal() function and works identical except that it recognizes mouse events and will automatically move the cursor up and down through the gets if the mouse is clicked within an active get.<br><br> DC_READMODAL() also supports extra parameters for handling mouse-buttons, determining the "active area" of the screen, etc.<br><br> DC_READMODAL() will support scrollable GETS automatically. GETS can be written anywhere outside the pre-established GET scroll region yet they will be visible only within the scroll region. When the cursor is bumped against the scroll boundaries, the GETS will scroll up/down or left/right. This technique allows you to design GET screens which are larger than the physical display size or a designated display window.<br><br> DC_READMODAL() makes it possible to edit arrays of GETS that are written to the screen in a FOR..NEXT loop.<br><br> DC_READMODAL() supports additional navigation features to make it easier to move thru a table of keys via the keyboard.<br><br> Alt-UpArrow : Moves to first GET directly above cursor position. If no GET exists directly above, then moves to closes GET above cursor position.<br><br> Alt-DnArrow : Moves to first GET directly below cursor position. If no GET exists directly below, then moves to closest GET below cursor position.<br><br> Alt-RtArrow : Moves to first GET directly to the right of the current GET.<br><br> Alt-LtArrow : Moves to first GET directly to the left of the current GET.<br><br> DC_READMODAL() will terminate the GETs by the same method as ReadModal() unless you have activated CUA-Compliant mode with DC_READCUA() in which the GETs will be terminated with the ENTER key.<br><br> DC_READMODAL() is "threadsafe". This means that it can be used as a replacement for ReadModal() when converting Clipper applications to Xbase++ applications that must maintain multiple CRT Windows running in separate threads. The function DC_ReadModalSize() is used to set the default size of the static array used by DC_READMODAL() to store static GET information. The default is 10. This means that the application is limited to 10 open threads. DC_ReadModalSize() should be set to the maximum number of threads expected.<br><br>

Syntax:

DC_ReadModal ( <aGetList>, ;
               [<nPos>], ;
               [<aActiveArea>], ;
               [<lConfirm>], ;
               [<nConfRow>], ;
               [<lNoUpdateEsc>], ;
               [<lProtect>], ;
               [<aMsg>], ;
               [<bCustomKey>], ;
               [<aCustomKeys>], ;
               [<lViewEdit>], ;
               [<lMouXWrite>], ;
               [<lMouRele>], ;
               [<lNoHelp>] ) -> lUpdated

Returns:

 .TRUE. if any gets were updated, .FALSE. otherwise.

Arguments:

<aGetList> is an array containing a list of Get objects to
edit.

<nPos> is the number of the GET to place into focus.
If no parameter is passed then GET #1 will be in focus.

<aActiveArea> is an array of 4 elements:

 Element   Type  Description
 -------   ----  -----------------------------------------
  [1]       N    Start Row
  [2]       N    Start Column
  [3]       N    End Row
  [4]       N    End Column
  [5]       A    Mouse buttons
                 (See DC_MOUSEKEY() for specification)

If no array is passed, then if the mouse is clicked outside
any active GETs, it will do nothing.  If an array is passed,
an the mouse is clicked outside the array coordinates, the
READ will be terminated exactly the same as hitting the
CTRL-W key.

<lConfirm> if .TRUE. will display a confirmation picklist, if
.FALSE. (default) will exit normally.

<nConfRow>  - If a value is passed the confirmation box
will start at the row number of the passed value, otherwise
it will be centered on the screen.

<lNoUpdateEsc> - If .TRUE., the mouse is clicked outside the
active area, and no gets were updated, then  Lastkey() will
return K_ESC.  If .FALSE. (default), the confirmation box will
be displayed.

<lProtect> - If .TRUE. the user will be allowed to navigate
thru the GET table, but will not be allowed to change any
data in the active gets.  If .FALSE. (default), then the Get
list will behave normally.

<aMsg> - This is an optional array of 6 parameters
defining the location of the screen to place messages defined
by the MESSAGE command line parameter in the @SAY..GET command.
Elements 1-4 are the screen coordinates ( nStRow, nStCol,
nEnRow, nEnCol respectively ).  Element 5 is a string defining
the color of the message window.  Element 6 is a logical value
defining whether or not each message line should be centered in
the message window.

<bCustomKey> - This is a code block which will be evaluated
in the "Apply Key" sub-function of DC_ReadModal(). This routine
checks which key has been pressed and sets the EXITSTATE based
on the key pressed.  The default action for keys is the same as
the standard Clipper GET system.  You can modify the action for
specified keys by adding your own CASE statements in a function
placed into the <bCustomKey> code block.  Three parameters are
passed to your custom function:

  1. The Inkey() value of the key pressed.
  2. The Get Object that is in focus.
  3. The GetList Object.

The <bCustomKey> code-block must return a LOGICAL .TRUE. if the
custom action was accomplished, .FALSE. otherwise.

<aCustomKeys> is an array of INKEY values and code blocks.  If
any key is pressed that matches an INKEY value in the array,
the associated code-block will be evaluated.

 Element  Type   Description
 -------  ----   ------------------------
   [1]   N     INKEY value
   [2]     B     Code block to evaluate when <INKEY> is pressed.

<lViewEdit> if .TRUE. will place DC_ReadModal() in the VIEW/EDIT
toggle mode.  In this mode, the GETS start out in VIEW mode.  In
VIEW mode the GETS may be navigated in the normal method, but
there will be no cursor displayed and pressing data entry keys
will not cause the GETS to be updated.  When the <ENTER> key is
pressed the EDIT mode is enabled at the currently selected GET
and the cursor is displayed.  Pressing <ESCAPE> will exit EDIT
mode and reestablish VIEW mode.  If this parameter is not passed
or is passed as a .FALSE, then normal editing will be enabled.

<lMouXWrite> if .TRUE. is equivalent to pressing the <CTRL-END>
or <F10> key to save the GETS whenever the mouse is clicked
outside the area established by the <aActiveArea> array.  If
this parameter is not passed or is passed as a .FALSE., then
clicking the mouse outside the <aActiveArea> region is
equivalent to pressing the <ESCAPE> key.

<lMouRele> if .TRUE. (default) will require that the mouse
button be released and pressed again before it will navigate
to the clicked-on GET.  If .FALSE. and the mouse button is
pressed on a GET, the clicked-on GET will immediately be
placed into focus.

<lNoHelp> if .TRUE. will disable the code block that calls
DC_HELPF1() when the F1 key is pressed.  The default is .FALSE.
Use this parameter if the F1 key has already been set to a
different procedure.

DC_READMODAL() also supports additional command line parameters
which may be added to the end of your @ SAY...GET command line.

(These options require #include 'DCGET.CH' in your source code):

FORCEVALID

 This option will require that the VALID statement in the
 GET be evaluated before the Get List can be exited, even if
 the GET is never entered by the operator. For example, if you
 have a GET that is not allowed to be empty, use this parameter
 in conjuction with DC_READEMPTY().

PICKLIST

 This option is used to paint a "down arrow" mouse button at
 the end of the GET variable on the screen which informs the
 operator that an additional picklist will pop-up if the
 operator single-clicks on the arrow or double-clicks within
 the GET area or if the operator presses the CTRL-J or
 CTRL-ENTER key while in the GET area.

DOUBLEPICK

 This option is used to paint a "down arrow" and "up arrow"
 mouse button at the end of the GET variable on the screen
 which informs the operator that clicking on the down arrow
 will decrease the value in the GET by the increment value
 and clicking on the up arrow will increase the value in the
 GET by the increment value.   This option was intended to be
 used with the DC_ReadIncr() function in the VALID statement.

PREEVAL <block>

 This option functions similar to the WHEN clause except it
 doesn't return a value and the block is evaluated before the
 WHEN block.

POSTEVAL <block>

 This option functions similar to the VALID clause except
 it doesn't return a value and the block is evaluated before
 the VALID block.

MESSAGE <aMessage>

 This option is used to display a message on the screen
 while the get is in focus.   <aMessage> may be a character
 string or an array of character strings.  The message will be
 displayed in the coordinates defined by the DC_READMSG()
 function, the SET READ MESSAGE TO <parameters> command, or
 the <aMessage> parameter passed to DC_ReadModal().

PROTECT

 This option will allow the user to enter the GET but not
 make any changes.  Any attempt to modify the data will cause
 a beep.

HIDE

 This option will hide all user input in the GET and display
 only an empty GET with the exception of an asterisk * at the
 cursor position.

CAPFIRST

 This parameter will automatically capitalize the first letter
 of each word typed into the GET.

APOINTER

 Editing an array of GETS that are displayed in a FOR..NEXT or
 DO..WHILE loop using an "incremented" or "decremented" pointer
 to each array element is not possible unless the value of the
 pointer is stored in CARGO.  This can be accomplished very
 easily by using the APOINTER <nVar> parameter at the end of
 your GET statement.  See Example 2.

CHECKBOX [MEMVAR] <xMemVar> [DELIMS <cDelims>]

 This option is used to define a GET as a "CHECK BOX".  A
 check box GET is used to toggle a logical variable whenever
 the mouse is clicked in the GET or when the cursor is moved
 to the GET and the ENTER key is pressed.  The <cDelims>
 parameter is a character string of 3 characters defining
 the delimeter characters to use to frame the check mark and
 the character to use to display the check mark when the
 check box is toggled to .TRUE.  If the DELIMS suboptions is
 not used then the default delimeters is "(*)".  <xMemVar> is
 the logical memory variable that will be toggled when the check
 box is toggled.

RADIOGROUP <nGroup> MEMVAR <xMemVar> [DELIMS <cDelims>] ;
           VALUE <xValue>

 This option is used to define a set of GETs as a "RADIO GROUP".
 A Radio Group GET is used to set a variable to a specified
 value whenever the mouse is clicked in the GET or when the
 cursor is moved to the GET and the ENTER key is pressed.
 <nGroup> is the number of the radio group that binds the
 separate GET items to a group.  The <cDelims> parameter is a
 character string of 3 characters defining the delimeter
 characters to use to frame the check mark and the character to
 use to display the check mark when the radio group item is
 selected.  If the DELIMS suboptions is not used then the
 default delimeters is "(*)".  <xMemVar> is the memory variable
 that will be updated when the radio group item is selected.
 <xValue> is the value that will be stored into <xMemVar> when
 the radio group item is selected.

HELPCODE <helpcode>

 This option is used to establish which help screen to display.
 If F1 or Alt-F1 is pressed while in the GET, the Help Code will be
 passed to the Help System.  This will override the INPUT VAR,
 PROC NAME, and any DC_HELPCODE() and force the dCLIP Help system to
 use the code in the GetList.

Notes:

See ReadModal() in the Clipper guides for more information.

Use the function DC_UPDATED() in place of UPDATED() if you are using DC_READMODAL() in place of READMODAL().

Use the function DC_GETACTIVE() in place of GETACTIVE() if you are using DC_READMODAL() in place of READMODAL().

Use the function DC_KILLREAD() in place of __KILLREAD() if you are using DC_READMODAL() in place of READMODAL().

Use the function DC_READBOX() to create a modal dialogue box and mouse-buttons for DC_READMODAL() and to establish the SCROLL region for the gets.

Use the function DC_READWINDOW() to establish the SCROLL region for the gets.

Examples:

 -- Example 1 --

 /* This example shows how DC_READMODAL() can be used
    to support pick-lists a memos */

 #include "dcget.ch"

 LOCAL GetList := {}, aReadArea, cSaveScreen,;
       cMemoGet := 'MEMO'

 cSaveScreen := DC_ReadBox( 9, 10, 19, 70,, @aReadArea )
 @ 11,15 say 'Enter Memo' GET cMemoGet ;
   valid dc_readmemo( @cMemo ) PICKLIST PROTECT
 @ 12,15 say 'Customer Number ' GET cust_nmbr ;
   valid dc_readempty(cust_nmbr) FORCEVALID
 @ 13,15 say '  Customer Name ' GET cust_name
 @ 14,15 say '         Street ' GET street
 @ 15,15 say '           City ' GET city
 @ 16,15 say '          State ' GET state ;
   valid dc_readclick( @state, {|d|d:=statelist()} ) ;
   PICKLIST
 @ 17,15 say '            Zip ' GET zip MESSAGE ;
   "Must be at least 5 digits"

 DC_READMODAL( GetList,, aReadArea,,,,,,;
              {|a,b|CustomKey(a,b)} )
 Return nil

 /* ----------------- */

 STATIC FUNCTION CustomKey ( nInkey, oGet )

 DO CASE
   /* Change PgDn key default action */
   CASE nInkey = K_PGDN
     oGet:ExitState := GE_BOTTOM
   /* Change PgUp key default action */
   CASE nInkey = K_PGUP
     oGet:ExitState := GE_TOP
   OTHERWISE
     RETURN .f.
 ENDCASE
 RETURN .t.

 -- Example 2 --

 /* This example demonstrates how DC_READMODAL() can be
    used to edit and scroll thru an Array of Field Data */

 #include "dcget.ch"

 LOCAL GetList := {}, aReadArea, cSaveScrn, aData, i

 USE DCPRINT
 aData := Array(Fcount())
 FOR i := 1 TO LEN( aData )
   aData[i] := FieldGet(i)
 NEXT
 cSaveScrn := DC_ReadBox( 10, 10, 20, 60,, @aReadArea )
 FOR i := 1 TO LEN(aData)
   @ i,12 SAY PADL(Field(i),10) GET aData[i] APOINTER i
 NEXT
 DC_READMODAL( GetList,,aReadArea )
 DC_Impl( cSaveScrn )
 RETURN nil

 -- Example 3 --

 /* This example demonstrates how DC_READMODAL() can be
    used to create CHECK BOXES and RADIO GROUPS */

 #include 'dcget.ch'

 FUNCTION junk

 LOCAL GetList := {}, aCheck := {' ','û',' '}, nLength,;
       aRadio := {'*',' ',' ','*',' ',' '}, ;
       lAscii := .f., lBackup := .t., lPrinter := .f., ;
       aReadArea, cComPort, ;
       cSaveScrn := DC_ReadBox( 3,5,21,70,,@aReadArea )

 /* -- Paint Check Boxes -- */
 @ 5,10 TO 11,35
 @ 5,12 SAY ' Check options below '
 @ 7,12 SAY 'Convert to ASCII ' GET aCheck[1] CHECKBOX ;
                  MEMVAR lAscii DELIMS '(û)'
 @ 8,12 SAY 'Keep Backup File ' GET aCheck[2] CHECKBOX ;
                  MEMVAR lBackup DELIMS '(û)'
 @ 9,12 SAY ' Copy to Printer ' GET aCheck[3] CHECKBOX ;
                  MEMVAR lPrinter DELIMS '(û)'

 /* -- Paint Radio Group 1 -- */
 @ 13,10 TO 19,35
 @ 13,12 SAY ' Select Page Length '
 @ 15,12 SAY ' 40 Lines  ' GET aRadio[1] RADIOGROUP 1 ;
             MEMVAR nLength DELIMS '(*)' VALUE 40
 @ 16,12 SAY ' 55 Lines  ' GET aRadio[2] RADIOGROUP 1 ;
             MEMVAR nLength DELIMS '(*)' VALUE 55
 @ 17,12 SAY ' 66 Lines  ' GET aRadio[3] RADIOGROUP 1 ;
             MEMVAR nLength DELIMS '(*)' VALUE 66

 /* -- Paint Radio Group 2 -- */
 @ 13,40 TO 19,65
 @ 13,42 SAY ' Select Com Port '
 @ 15,42 SAY ' Com 1  ' GET aRadio[4] RADIOGROUP 2 ;
             MEMVAR cComPort DELIMS '(*)' VALUE 'COM1'
 @ 16,42 SAY ' Com 2  ' GET aRadio[5] RADIOGROUP 2 ;
             MEMVAR cComPort DELIMS '(*)' VALUE 'COM2'
 @ 17,42 SAY ' Com 3  ' GET aRadio[6] RADIOGROUP 2 ;
             MEMVAR cComPort DELIMS '(*)' VALUE 'COM3'

 DC_READMODAL( GetList,,aReadArea )
 DC_Impl( cSaveScrn )
 RETURN { lAscii, lBackup, lPrinter, nLength, cComport }

Files:

_DCGETSY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_reader()
   dc_readbox()
   dc_readmodalsize()


dc_readmodalsize()

Set the size of the static array for DC_ReadModal()

DC_ReadModal() is "threadsafe". This means that it can be used as a replacement for ReadModal() when converting Clipper applications to Xbase++ applications that must maintain multiple CRT Windows running in separate threads. The function DC_READMODALSIZE() is used to set the default size of the static array used by DC_ReadModal() to store static GET information. The default is 10. This means that the application is limited to 10 open threads. DC_READMODALSIZE() should be set to the maximum number of threads expected.

Syntax:

DC_ReadModalSize ( [<nSize>] ) -> nOldSize

Returns:

A numeric value equal to the previous size.

Arguments:

 <nSize> is the maximum number of threads in the application.

Examples:

DC_READMODALSIZE( 15 )

Files:

_DCGETSY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()


dc_readnav()

Enable an alternative navigation method for GETS

DC_READNAV( .t. ), is used to set the alternate navigation method when using DC_ReadModal(). Normal navigation in GETS has the DOWN, ENTER and TAB keys moving to the next get in the Get List and the UP and SHIFT-TAB key moving to the previous Get in the Get List. In the alternate method the ENTER key still behaves the same, however the TAB key will move to the next get to the right of the get in focus in the same row, the SHIFT-TAB key will move to the next get to the left of the get in focus in the same row, and the UP and DOWN keys will move to the closest GET on the screen that is above or below the get in focus. The Alternate Navigation mode is also toggled by the ALT-N key.

Syntax:

DC_ReadNav ( [<lMode>] ) -> lMode

Returns:

 The current setting.

Arguments:

<lMode> if .TRUE. will set the alternate navigation
method.  The default is .FALSE.

Files:

_DCGETSY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()
   dc_readalt()
   dc_readcua()


dc_readvar()

Update a check box or Radio Button GET

DC_READVAR() is a function designed to be used in a code block that is passed to DC_ADDCARGO() and evaluated when the mouse is clicked in a Radio Button or Check Box GET. See the DCGET.CH file for examples of how to use DC_READVAR().<br><br>

Syntax:

DC_ReadVar ( [<xMemVar>], ;
             [<nElement>], ;
             [<xValue>], ;
             [<lCheck>], ;
             [<cMemVar>] ) -> nil

Returns:

 NIL

Arguments:

@<xMemVar> is the value of the memvar to update.  If this
parameter is not passed then the name of a PRIVATE or
PUBLIC memvar must be passed as <cMemVar>.

<nElement> is used only if <xMemVar> is an array.  The
value of this parameter determines which array element to
update.

<xValue> is used only if <xMemVar> or <cMemVar> is a
Radio Button and not a Check Box.  This is the value to
stuff into <xMemVar> or &<xMemVar>.

<lCheck> if .TRUE. establishes <xMemVar> as a logical Check
box memvar, otherwise it is a Radio Button memvar of any
type.

Notes:

This function must be used with DC_READMODAL().

Examples:

 See DCGET.CH

Files:

_DCGETSY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()
   dc_addcargo()


dc_readwindow()

Establish scroll-region for DC_ReadModal() GETS

DC_READWINDOW() is used to establish a window area of the screen to be used by the next call to DC_READMODAL().<br><br> DC_READMODAL() will support scrollable GETS automatically. GETS can be written anywhere outside the pre-established GET scroll region yet they will be visible only within the scroll region. When the cursor is bumped against the scroll boundaries, the GETS will scroll up/down or left/right. This technique allows you to design GET screens which are larger than the physical display size or a designated display window.<br><br> DC_READWINDOW() stores the coordinates of the screen to a static array which is later monitored by DC_GETDEVOUT(), DC_GETDISPLAY(), and DC_READMODAL() to prevent @SAY..GETS from being displayed outside the window region. Such GETS will be added to the Get List but will only be accessible when the Get List is "scrolled" by bumping against the scroll boundaries with a cursor key.

Syntax:

DC_ReadWindow ( [<aCoord>] ) -> aCoord

Returns:

 An array containing the previously established screen
 coordinates.

Arguments:

<aCoord> is an array containing the screen coordinates.

  Element   Type  Description
  -------   ----  -----------------------------------------
   [1]       N    Start Row
   [2]       N    Start Column
   [3]       N    End Row
   [4]       N    End Column

Notes:

DC_READWINDOW() must be called before displaying any GETS with the @SAY..GET command.

Examples:

 #include "dcget.ch"

 LOCAL GetList := {}, aData, i

 USE DCPRINT
 aData := Array(Fcount())
 FOR i := 1 TO LEN( aData )
   aData[i] := FieldGet(i)
 NEXT
 DC_READWINDOW( { 10, 10, 20, 60 } )
 FOR i := 1 TO LEN(aData)
   @ i,12 SAY PADL(Field(i),10) GET aData[i] APOINTER i
 NEXT
 DC_ReadModal( GetList,,aReadArea )
 RETURN nil

Files:

_DCGETSY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()
   dc_readbox()


dc_recall()

Recall record(s) that were previously marked for deletion

DC_Recall() is used to recall records which were previously marked for deletion based on a set of conditions. A GUI dialog is displayed for the user to select the conditions.

Syntax:

 DC_Recall() -> lStatus

Returns:

 A logical .TRUE. if records were recalled successfully, .FALSE.
 otherwise.

Arguments:

 None.

Examples:

 . USE EXPRESS INDEX EXPRESS.CDX SHARED
 . DC_Recall()

Files:

_DCDELE.PRG, DCLIP1.DLL

See Also:

   dc_delete()


dc_reclock()

Lock the current record

DC_RECLOCK() is used to lock the currently selected record before attempting to replace field data.<br><br>

Syntax:

 DC_RecLock ( [<nWaitTime>], ;
              [<lDisplayError>] ) -> lStatus

Returns:

 A logical .TRUE. if the record is successfully locked.

Arguments:

<nWaitTime> is the number of seconds to wait for the system to
return a lock before returning the status or the error message.
(0 = wait forever).

<lDisplayError> if .true. will display an operator error
message if the record cannot be locked. (default) or if .false.
will not display an error message to the operator.

Examples:

 if DC_RECLOCK( 5 )
   replace cust_nmbr with cCustNmbr
 else
   break
 endif

Files:

_DCLOCK.PRG, DCLIPX.DLL

See Also:

   dc_addrec()
   dc_filock()


dc_rectag()

Build or add to a Record Tag Array

DC_RECTAG() is used to add or remove record numbers from an array of record numbers that can be used with all database commands for performing database operations on records that are "tagged". <br><br> DC_RECTAG() will first check for a logical field in the database named "TAG" and will operate on this field. If this field does not exist, it will operate on a PUBLIC array named DCTAGS.<br><br>

Syntax:

 DC_RecTag( [<lClear>], ;
            [<aTags>], ;
            [<bFor>], ;
            [<bWhile>], ;
            [<nNext>], ;
            [<nRec>], ;
            [<lRest>] ) - > aTags

Returns:

 A pointer to an array of tagged numbers.

Arguments:

<lClear> will remove record numbers from the tag array that
meet the specified conditions, otherwise records will be
added.

<aTags> is an existing array of record numbers which will
display the TAG marker in the browse display.  If no
argument is given then the public DCTAGS array will be
used.

See the Xbase++ DBEVAL() function on how to use the <bFor>,
<bWhile>, <nNext>, <nRec>, <lRest> parameters.

Notes:

CAUTION: The eXPress++ tagging system is designed for ad-hoc tagging of records using simple menu selection and database commands. You will notice a gradual speed detioration as you add more records to the tag array when browsing. This is because the DC_TAGGED() function must scan more records in the array. It is recommend that you refrain from tagging more than 1000 records or you may experience unacceptable slowness during browsing.

If you need a tagging system that will support a much larger number of records, it is recommended that you add a TAG (logical) field to your database.

Examples:

 . use customer
 . dc_rectagclear()
 . aTags := {}

  // tag all records with a balance greater than 0
 . aTags := DC_RECTAG(.f., aTags, {||balanceɬ} )

  // untag all records in Los Angeles
 . aTags := DC_RECTAG(.t., aTags, {||zip='90'.or.zip='91'} )

 . list cust_name for dc_tagged(aTags)

Files:

_DCRTAG.PRG, DCLIP2.DLL

See Also:

   dc_rectagclear()
   dc_tagrecord()
   dc_rectagarray()
   dc_rectagtoggle()
   TAG


dc_rectagarray()

Gets or Sets the array to be used for Record Tagging

DC_RecTagArray() is used to Get or Set a pointer to the array that will be used for all record tagging operations.<br><br><br><br><br><br>

Syntax:

 DC_RecTagToggle ( [<aTags>] ) -> <aOldTags>

Returns:

 A pointer to an array of tagged numbers.

Arguments:

<aTags> is an array of tags.  If no array is passed then
the currently selected work area portion of the public
DCTAGS array will used.

Notes:

CAUTION: The eXPress++ tagging system is designed for ad-hoc tagging of records using simple menu selection and database commands. You will notice a gradual speed detioration as you add more records to the tag array when browsing. This is because the DC_TAGGED() function must scan more records in the array. It is recommend that you refrain from tagging more than 1000 records or you may experience unacceptable slowness during browsing.

If you need a tagging system that will support a much larger number of records, it is recommended that you add a TAG (logical) field to your database.

Examples:

  use customer
  dc_rectag(,,{||balanceɬ})
  count to x for dc_tagged()
  ? x
 123
  DC_RECTAGCLEAR()
  count to x for dc_tagged()
  ? x
 0

Files:

_DCRTAG.PRG, DCLIP2.DLL

See Also:

   dc_rectag
   dc_tagrecord()


dc_rectagclear()

Clear the Record Tag Array

DC_RECTAGCLEAR() will clear out all tags in the public DCTAGS array for the current work area.<br><br><br><br>

Syntax:

 DC_RecTagClear ( [<aTags>] ) -> nil

Returns:

 A pointer to an array of tagged numbers.

Arguments:

<aTags> is an array of tags.  If no array is passed then
the currently selected work area portion of the public
DCTAGS array will be cleared.

Notes:

CAUTION: The eXPress++ tagging system is designed for ad-hoc tagging of records using simple menu selection and database commands. You will notice a gradual speed detioration as you add more records to the tag array when browsing. This is because the DC_TAGGED() function must scan more records in the array. It is recommend that you refrain from tagging more than 1000 records or you may experience unacceptable slowness during browsing.

If you need a tagging system that will support a much larger number of records, it is recommended that you add a TAG (logical) field to your database.

Examples:

  use customer
  dc_rectag(,,{||balanceɬ})
  count to x for dc_tagged()
  ? x
 123
  DC_RECTAGCLEAR()
  count to x for dc_tagged()
  ? x
 0

Files:

_DCRTAG.PRG, DCLIP2.DLL

See Also:

   dc_rectag
   dc_tagrecord()
   dc_rectagarray()


dc_rectagtoggle()

Toggle the Record Tag on the current record

DC_RecTagToggle() is used to toggle the value of the record tag on the current record. If the record number exists in the tag array, then it will be removed, otherwise it will be added.<br><br><br><br>

Syntax:

 DC_RecTagToggle ( [<aTags>] ) -> nil

Returns:

 A pointer to an array of tagged numbers.

Arguments:

<aTags> is an array of tags.  If no array is passed then
the currently selected work area portion of the public
DCTAGS array will be cleared.

Notes:

CAUTION: The eXPress++ tagging system is designed for ad-hoc tagging of records using simple menu selection and database commands. You will notice a gradual speed detioration as you add more records to the tag array when browsing. This is because the DC_TAGGED() function must scan more records in the array. It is recommend that you refrain from tagging more than 1000 records or you may experience unacceptable slowness during browsing.

If you need a tagging system that will support a much larger number of records, it is recommended that you add a TAG (logical) field to your database.

Examples:

  use customer
  dc_rectag(,,{||balanceɬ})
  count to x for dc_tagged()
  ? x
 123
  DC_RECTAGCLEAR()
  count to x for dc_tagged()
  ? x
 0

Files:

_DCRTAG.PRG, DCLIP2.DLL

See Also:

   dc_rectag
   dc_tagrecord()
   dc_rectagarray()


dc_regdelete()

Delete a key from the Windows Registry

DC_REGDELETE() is used to delete a key from the Windows Registry.

Syntax:

DC_RegQuery( [<nHKey>], ;
             <cRegSubKey> ) -> lSuccess

Returns:

 The value stored in the registry.  This may be a value of any
 type.

Arguments:

<nHKey> is the key value of the registry item to query.  The
default is HKEY_LOCAL_MACHINE.  The available options are defined
in DCREG.CH.

 HKEY_NO_KEY
 HKEY_CLASSES_ROOT
 HKEY_CURRENT_USER
 HKEY_LOCAL_MACHINE
 HKEY_USERS

<cRegSubKey> is the sub key in the registry.

Examples:

DC_RegDelete( HKEY_LOCAL_MACHINE, '\Donnay Software\eXpress++' )

Files:

_DCREG.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_regwrite()
   dc_regquery()


dc_regdeletevalue()

Delete a value from the Windows Registry

DC_RegDeleteValue() is used to delete a value from the Windows Registry.

Syntax:

DC_RegQuery( [<nHKey>], ;
             <cRegSubKey>, ;
             <cEntryName> ) -> lSuccess

Returns:

A numeric 0 if the delete was successful, otherwise a Windows error code.

Arguments:

<nHKey> is the key value of the registry item to query.  The
default is HKEY_LOCAL_MACHINE.  The available options are defined
in DCREG.CH.

 HKEY_NO_KEY
 HKEY_CLASSES_ROOT
 HKEY_CURRENT_USER
 HKEY_LOCAL_MACHINE
 HKEY_USERS

<cRegSubKey> is the sub key in the registry.

<cEntryName> is the name of the value in the registry.

Examples:

DC_RegDelete( HKEY_LOCAL_MACHINE, '\Donnay Software\eXpress++\windows','MainWindow' )

Files:

_DCREG.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_regwrite()
   dc_regquery()
   dc_regdelete()


dc_regionarray()

Return an array of region coordinates for a dialog

DC_RegionArray() returns a multi-dimensional array which can be used by @ .. DCPUSHBUTTON or by any other dialog window to crop the dialog to a specified shape. DC_RegionArray() will return an array for creating Octagon, Diamond, or Ellipse pushbuttons or dialogs.

Syntax:

DC_RegionArray( <nMode>, ;
                <nWidth>, ;
                <nHeight> ) -> aRegion

Returns:

A multidimensional array.

Arguments:

<nMode> is a numeric value defined in DCDIALOG.CH.
See the below table.

<nMode>                 Description
----------------------- ----------------------------------------
DCGUI_REGION_OCTAGON    Octagon shape
DCGUI_REGION_DIAMOND    Diamond shape
DCGUI_REGION_ELLIPSE    Ellipse or circle

<nWidth> is the width in pixels of the region.

<nHeight> is the height in pixels of the region.

Examples:

* ---- Example 1 ---- *

// Circular region of 100 pixels width and height

@ 0,330 DCPUSHBUTTON ;
      STATIC ;
      ACTION {||msgbox('Ugh')} ;
      SIZE 100,100 ;
      REGION DC_RegionArray( DCGUI_REGION_ELLIPSE, 100 ) ;
      PIXEL ;
      FANCY ;
      BITMAP 'smileyup.jpg','smileydown.jpg','smileyneutral.jpg'

* ---- Example 2 ----- *

oDlg := XbpDialog():new(AppDeskTop(),,{0,0},{100,100})
oDlg:create()
aRegion := DC_RegionArray( DCGUI_REGION_OCTAGON, 100 )
DC_SetRegion( oDlg, aRegion )

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_setregion()
   dc_setregionellipse()
   @ DCPUSHBUTTON


dc_regquery()

Read a parameter from the Windows Registry

DC_REGQUERY() is used to read a specified value from the Windows registry.

Syntax:

DC_RegQuery( [<nHKey>], ;
             <cRegSubKey>, ;
             <cEntryName> ) -> xValue

Returns:

 The value stored in the registry.  This may be a value of any
 type.

Arguments:

<nHKey> is the key value of the registry item to query.  The
default is HKEY_LOCAL_MACHINE.  The available options are defined
in DCREG.CH.

 HKEY_NO_KEY
 HKEY_CLASSES_ROOT
 HKEY_CURRENT_USER
 HKEY_LOCAL_MACHINE
 HKEY_USERS

<cRegSubKey> is the sub key in the registry.

<cEntryName> is the entry name of the item.

Examples:

Examples:

? DC_RegQuery( nil, 'SYSTEM\Setup', 'SystemPartition' )

\Device\Harddis0\Partition1

? DC_RegQuery( nil, 'Software\Clients\Contacts', '' )

Address Book

? DC_RegQuery( nil, 'Software\Clients\Mail', '' )

Outlook Express

? DC_RegQuery( nil, 'Software\Clients\Mail', 'Outlook Express' )

Outlook Express

? DC_RegQuery( nil, 'Software\Clients\Mail\Outlook Express', ;
               DLLName )

C:\Program Files\Outlook Express\msimnui.dll

Files:

_DCREG.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_regwrite()
   dc_iniread()


dc_regqueryautorestore()

displays a dialog that lists all item in the registry defined by DC_AutoRestoreWindow()

DC_RegQueryAutoRestore() displays a dialog with 2 browses. <br><br>(1) lists all items in the Windows section of the registry that is defined by DC_AutoRestoreWindow(). <br><br>(2) lists all items in the Browse section of the registry that is defined by DC_AutoRestoreBrowse(). <br><br>Items can be tagged for deletion.

Syntax:

DC_RegQueryAutoRestore() -> NIL

Files:

_DCREG.PRG, DCLIPX.DLL

See Also:

   dc_autorestorewindow()


dc_regquerybranch()

Returns all the values of a registry branch into an array.

DC_ReqQueryBranch() returns all the values of a registry branch into an array. The array will contain the value name plus the data.

Syntax:

DC_RegQueryBranch( <nHKey>, ;
                   <cSubKey>, ;
                   <nKey> ) -> <aBranch>

Arguments:

<nHKey> is the key value of the registry item to query.  The
default is HKEY_LOCAL_MACHINE.  The available options are defined
in DCREG.CH.

 HKEY_NO_KEY
 HKEY_CLASSES_ROOT
 HKEY_CURRENT_USER
 HKEY_LOCAL_MACHINE
 HKEY_USERS

<cRegSubKey> is the sub key in the registry.

Files:

_DCREG.PRG, DCLIPX.DLL

See Also:

   dc_regquery()


dc_regwrite()

Write a parameter to the Windows Registry

DC_REGWRITE() is used to write a specified value to the Windows registry.

Syntax:

DC_RegWrite( [<nHKey>], ;
             <cRegSubKey>, ;
             <cEntryName>, ;
             <xValue>, ;
             [<nType>] ) -> lStatus

Returns:

 A logical value.

Arguments:

<nHKey> is the key value of the registry item to write.  The
default is HKEY_LOCAL_MACHINE.  The available options are defined
in DCREG.CH.

 HKEY_NO_KEY
 HKEY_CLASSES_ROOT
 HKEY_CURRENT_USER
 HKEY_LOCAL_MACHINE
 HKEY_USERS

<cRegSubKey> is the sub key in the registry.

<cEntryName> is the entry name of the item.

<xValue> is the value to write.  This may be any data type that
can be converted to a binary value with a maximum length of 32k.

<nType> is the type of value to store to the registry.
If this parameter is not used, then the type is calculated from the
valtype of <xValue>.

Examples:

DC_RegWrite( nil, 'Software\eXPress++', 'UserID', 'BEAR' )
DC_RegWrite( nil, 'Software\eXPress++', 'UserPassword', ;
                   DC_Encrypt(cPassWord) )

Files:

_DCREG.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_regquery()
   dc_iniwrite()


dc_replace()

Assign new values to field variables using GUI dialog

DC_Replace() is used to assign new values to field variables in the current database, based on conditions selected in a GUI dialog.<br><br> Replacement values may be literal or expressions.<br><br> A progress bar is constantly updated during the replacement and records are automatically locked and unlocked thus allowing replacements on shared databases.<br><br><br><br><br><br>

Syntax:

 DC_Replace() -> lStatus

Returns:

 A logical .TRUE. if the replacement was successful.

Arguments:

 None.

Examples:

 . USE COLLECT
 . DC_Replace()

Files:

_DCREPL.PRG, DCLIP2.DLL

See Also:


dc_restoreevents()

Restore all events in the event queue from an array

DC_SaveEvents() will save all events in the event queue of the current thread to an array and clear all pending events from the event Queue. The event queue can then be later restored by DC_RESTOREEVENTS(). This is sometimes necessary to affect correct behavior of dialog windows when a series of events must be interrupted to display a new window.<br><br>

Syntax:

 DC_RestoreEvents( <aEvents> ) -> NIL

Returns:

 Nil.

Arguments:

 <aEvents> is a two-dimensional array that was created with
 DC_SaveEvents().

Files:

_DCFUNCT.PRG/.OBJ, DCLIPX.DLL

See Also:

   dc_completeevents()
   dc_clearevents()
   dc_saveevents()


dc_restset()

Restore all SETs from an array

DC_RESTSET() will restore the Clipper SET environment from an array created by DC_SAVESET(). The Clipper SET environment consists of 38 variables which are modified with the SET() function. DC_SAVESET() provides a method of saving an environment to be restored by DC_RESTSET().

Syntax:

DC_RestSet ( <aSets> ) -> nil

Returns:

 nil

Arguments:

<aSets> is an array created by DC_SAVESET().

Examples:

 aSaveSet := dc_saveset()
 set default to \customer\data
 set path to \myreport
 set printfile to print.txt
 use customer
 report form custlist
 DC_RESTSET( aSetSave )

Files:

_DCSETK.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_saveset()


dc_reuseexclusive()

Re-Use a database Exclusive

DC_ReUseExclusive() is a handy function for testing if a file is already opened exclusive. If not, it prompts the operator with the choice to reopen it exclusive to complete the operation.<br><br>

Syntax:

 DC_ReUseExclusive() -> lStatus

Returns:

 A logical .TRUE. if the file is already opened exclusive or
 if the file could be reopened exclusive, .FALSE. otherwise.

Arguments:

 None.

Examples:

 USE COLLECT SHARED
 lOk := DC_ReUseExclusive()
 IF lOk
   dbZap()
 ELSE
   DC_WinAlert( 'Sorry, try again later' )
 ENDIF

Files:

_DCUSE.PRG

See Also:

   dc_usearea()


dc_saveevents()

Clear all events out of the Event Queue

DC_SAVEEVENTS() will save all events in the event queue of the current thread to an array and clear all pending events from the event Queue. The event queue can then be later restore by DC_RestoreEvents(). This is sometimes necessary to affect correct behavior of dialog windows when a series of events must be interrupted to display a new window.<br><br>

Syntax:

 DC_SaveEvents() -> aEvents

Returns:

 A two-dimensional array.

Arguments:

None.

Files:

_DCFUNCT.PRG/.OBJ, DCLIPX.DLL

See Also:

   dc_completeevents()
   dc_clearevents()
   dc_restoreevents()


dc_saveset()

Save all SETs to an array

DC_SAVESET() will save the Clipper SET environment to an array. The Clipper SET environment consists of 38 variables which are modified with the SET() function. DC_SAVESET() provides a method of saving an environment to be restored by DC_RESTSET().

Syntax:

DC_SaveSet () -> aSets

Returns:

 An array that contains the contents of the SET environment.

Arguments:

 None

Examples:

 aSaveSet := DC_SAVESET()
 set default to \customer\data
 set path to \myreport
 set printfile to print.txt
 use customer
 report form custlist
 dc_restset( aSetSave )

Files:

_DCSETK.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_restset()


dc_say()

Perform @..SAYs relative to coordinates in dc_expl() window

DC_SAY() is a Dual-Mode function which is used to write text to a window that was created by DC_EXPL(). This function uses either "relative" addressing so the text written in the window is relative to the starting coordinates of the window or "fixed" addressing so the text written in the window is relative to the starting screen coordinates. Fixed addressing is provided for compatibility with existing Clipper applications that are being migrated to Xbase++.<br><br>

Syntax:

DC_Say ( [<aSaveScreen>], ;
         <nRow>, ;
         <nCol>, ;
         <cText>, ;
         [<lOk>], ;
         [<cFont>], ;
         [<cColor>] ) -> nil

Returns:

 NIL

Arguments:

<aSaveScreen> is an array of screen information that was
originally returned by DC_EXPL().  If no parameter is
passed, then the static array posted by the last usage of
DC_EXPL() or the DCEXPLODE command will be used for the
screen information.  If no call to DC_EXPL() or DCEXPLODE
is made since the last call to DC_IMPL() or DCIMPLODE,
then the text is written to the CRT window and treated as
a normal @..SAY.

<nRow> is the row position within the window. If the
RELATIVE parameter was passed to DC_EXPL() when the window
was created, then this must be a coordinate which is
relative to 0,0 of the window, otherwise it must be relative
to 0,0 of the screen.

<nCol> is the column position within the window. If the
RELATIVE parameter was passed to DC_EXPL() when the window
was created, then this must be a coordinate which is
relative to 0,0 of the window, otherwise it must be relative
to 0,0 of the screen.

<cText> is the text to display.

<lOk> if .TRUE. will display an "OK" button on the bottom
of the Window and pause program execution until the user
hits ENTER or clicks the mouse on the OK button.

<cFont> if passed, will override the font that was passed
to DC_EXPL() for this Say object only, otherwise the
default font will be used.  This parameter is used in GUI
mode only.

<cColor> is a valid Clipper color string.  If this parameter
is not passed, then the background color of the window will
be used.

Examples:

PROCEDURE XTest()

LOCAL aText

aText := { "Enter a name to search.",;
           "The name must start with",;
           "an alphabet character" }

_disp_msg( 10,10,16,40,aText )

RETURN

/* --------- */

STATIC PROCEDURE _disp_msg ( nSrow, nScol, nErow, nEcol, aText )

LOCAL cScreen, i

DC_Gui(.t.)  // display a gui dialogue

cScreen := dc_expl( nSrow, nScol, nErow, nEcol )
for i := 1 to len(aText)
  DC_SAY( cScreen, i+1, 2, aText[i] )
next

DC_Pause(3)
DC_Impl(cScreen)

RETURN

Files:

_DCEXPL.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_expl()


dc_saycenter()

Write a string in the center of an area of the screen

DC_SAYCENTER() is a handy way to write a string exactly in the center of a defined area of the screen.

Syntax:

DC_SayCenter ( <nRow>, ;
               <nStCol>, ;
               <nEnCol>, ;
               <cString> ) -> nil

Returns:

 NIL

Arguments:

<nRow> is the row position of the screen.

<nStCol> is the start column.

<nEnCol> is the end column.

<cString> is the string to say.

Examples:

 dc_expl( 12, 20, 14, 50 )
 DC_SAYCENTER( 13, 20, 50, 'Center this' )

Files:

_DCSAY.PRG/.OBJ, DCLIPX.LIB


dc_scopeexpress

Use eXPress++ scoping system in lieu of Xbase++

DC_ScopeExpress(.T.) is used to override the Xbase++ scoping system (Xbase++ 1.7 and later) and use the eXPress++ scoping system when using the following functions:<br><br>DC_SetScope() DC_ClrScope() DC_DbGoTop() DC_DbGoBottom() DC_DbSkip() DC_DbSeek() DC_DbLocate()<br><br>Normally, calls to the above functions will simply be routed to the associated Xbase++ function. For example, DC_SetScope() will call dbSetScope(). Due to reports that the Xbase++ 1.7 scoping system does not behave correctly in existing eXPress++ applications DC_ScopeExpress(.T.) will correct the problem.<br><br>It has since been reported that scoping in Xbase++ 1.8 behaves correctly, therefore DC_ScopeExpress(.t.) is not needed with Xbase++ 1.8.

Syntax:

DC_ScopeExpress( [<lScopeExpress>] ) -> lOldSetting

Arguments:

<lScopeExpress> if .TRUE. will enable the eXPress++ scoping
system.  If .FALSE. and the version of Xbase++ is 1.7 or later,
the Xbase++ scoping system will be used.

Files:

_dcscope.prg

See Also:

   dc_setscope()


dc_scrldata()

Display a database vertical scroll bar

DC_SCRLDATA() is used to display a vertical scroll bar on the screen to show the relative position of the current record pointer within the database.<br><br> This function will worked with indexed or non-indexed databases but not with "filtered" databases. A thumb 'þ' character is displayed in the scroll bar in the row position representative of the relative position of the current record within the database. If the relative position cannot be calculated then only the background characters of the scroll bar will be displayed and a '?' will be displayed at the first row position of the scroll-bar.

Syntax:

DC_ScrlData( <nStartRow>, ;
             <nEndRow>, ;
             <nColumn>, ;
             <lDispBar>, ;
             <xScopeTop>, ;
             <xScopeBottom> ) -> nRowPointer

Returns:

 The row position of the scroll-bar.

Arguments:

<nStartRow> is the start display row.

<nEndRow> is the end display row.

<nColumn> is the display column.

<lDispBar> if .TRUE. (default) will display the bar,
otherwise only the row pointer will be returned.

<xScopeTop> and <xScopeBottom> are optional values to
determine the number of active records for calculating the
position of the scroll bar.  This will work only if an index
is selected and the scope values match the current index.

Notes:

If the scroll-bar slows down your system on large indexed databases, then it can be enabled or disabled on the fly with DC_SCRLDENABLE().

Examples:

 use customers index custname

 // display relative position of current record pointer
 // for all customers starting with "H" and ending with "R"
 DC_SCRLDATA( 0, 24, 79, .t., "H", "R" )

Files:

_DCSCRLD.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_scrldmou()


dc_scrldmou()

Return a record pointer from database scroll-bar mouse-click

DC_SCRLDATA() is used to display a vertical scroll bar on the screen to show the relative position of the current record pointer within the database.<br><br> This function will worked with indexed or non-indexed databases but not with "filtered" databases. A 'þ' character is displayed in the scroll bar in the row position representative of the relative position of the current record within the database. If the relative position cannot be calculated then only the background characters of the scroll bar will be displayed.

Syntax:

DC_ScrlDMou( <nStartRow>, ;
             <nEndRow>, ;
             <nMouseRow>, ;
             <xScopeTop>, ;
             <xScopeBottom>, ;
             [<lPageMode>] ) -> nRecNo

Returns:

 A record number to GO TO.

Arguments:

<nStartRow> is the start display row.

<nEndRow> is the end display row.

<nMouseRow> is clicked row of the mouse.

<xScopeTop> and <xScopeBottom> are optional values to
determine the number of active records for calculating the
position of the scroll bar.  This will work only if an index
is selected and the scope values match the index key.

<lPageMode> if .TRUE. (default ) will return a value that
is one page higher than <nCurrVal> if the mouse is clicked
below the current pointer or a value that is one page
lower than the <nCurrVal> if the mouse is clicked above
the current pointer.  If <lPageMode> is .FALSE. then the
value returned is a number proportional to the mouse-click
position within the scroll-bar region.

Examples:

 use customers index custname

 // return record pointer based on scroll-bar mouse-click
 // for all customers starting with "H" and ending with "R"
 dc_mougetpos( @nMouseRow, @nMouseCol )
 nRecNo := DC_SCRLDMOU( 0, 24, nMouseRow, "H", "R" )

Files:

_DCSCRLD.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_scrldata()
   dc_scrlvmou()


dc_scrldthumb()

Enable display of database vertical scroll bar thumb

DC_SCRLDTHUMB() is used to enable or disable the display of the thumb "þ" within the scroll-bar region of the vertical scroll-bars on database browse windows. This is a relative position indicator that is calculated on indexed databases by a special algorithm that can consume time on large databases and thereby cause "pauses" in the browse window updates. If these pauses start becoming noticable or cause unacceptable performance, then it is recommended that you disable the scroll-bar thumb with DC_SCRLDTHUMB(.f.) in your source code, SET THUMB OFF at the dot-prompt or THUMB=OFF in your DCLIP.SYS file.

Syntax:

DC_ScrlDThumb( <lEnable> ) -> lStatus

Returns:

 A logical value equal to the current setting.

Arguments:

<lEnable> if .TRUE. will enable the thumb, otherwise it will
be disabled.

Examples:

 use customers index custname
 DC_SCRLDTHUMB( .f. ) // speed up browsing
 dc_browsedb()
 use testdata index testdata
 DC_SCRLDTHUMB( .t. ) // show relative position
 dc_browsedb()

Files:

_DCSCRLD.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_scrldata()


dc_scrlhbar()

Display a horizontal scroll bar

DC_SCRLHBAR() is used to display a horizontal scroll bar on the screen to show the relative position of an array pointer within the array or the relative position of a numeric pointer between minimum and maximum selectable values.

Syntax:

DC_ScrlHBar( <nStartCol>, ;
             <nEndCol>, ;
             <nRow>, ;
             <nCurVal>, ;
             <nMinVal>, ;
             <nMaxVal> ) -> nColPointer

Returns:

 The column position of the scroll bar.

Arguments:

<nStartCol> is the start display column.

<nEndCol> is the end display column.

<nRow> is the display row.

<nCurVal> is the current value.  This could be an array
element.

<nMinVal> is the minimum value.  If an array, then this
should be 1 or the minimum selectable value.

<nMaxVal> is the maximum value.  If an array, then this
should be the number of items in the array or the maximum
selectable value.

Examples:

 aFields := array(fcount())
 aFields( aFields )      // create an array of field names
 nPointer := 10
 // display scroll bar showing relative position
 DC_SCRLHBAR( 0, 79, 24, nPointer, 1, LEN(aFields )

Files:

_DCSCRL.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_scrlhmou()
   dc_scrlvbar()


dc_scrlhmou()

Return an array pointer from horizontal scroll-bar mouse-click

DC_SCRLHMOU() is used with a horizontal scroll bar on the screen to return an array pointer based on the relative mouse-click position within the scroll bar.

Syntax:

DC_ScrlHMou( <nStartCol>, ;
             <nEndCol>, ;
             <nMouseCol>, ;
             <nMinVal>, ;
             <nMaxVal>, ;
             <nCurrVal>, ;
             [<lIncrMode>] ) -> nPointer

Returns:

 A pointer to an array element.

Arguments:

<nStartCol> is the start display column.

<nEndCol> is the end display column.

<nMouseCol> is the clicked mouse column.

<nMinVal> is the minimum value.  If an array, then this
should be 1 or the minimum selectable value.

<nMaxVal> is the maximum value.  If an array, then this
should be the number of items in the array or the maximum
selectable value.

<nCurrVal> is the current value.  This is needed to
determine the relative position of the mouse with respect
to the current position.

<lIncrMode> if .TRUE. (default )will return a value that is
one number higher than <nCurrVal> if the mouse is clicked
to the right of the current pointer or a value that is one
number lower than the <nCurrVal> if the mouse is clicked
to the left of the current pointer.  If <lIncrMode> is
.FALSE. then the value returned is a number proportional
to the mouse-click position within the scroll-bar region.

Examples:

 aFields := array(fcount())
 aFields( aFields ) // create an array of field names

 // get an array element based on mouse position
 dc_mougetpos( @nMouseRow, @nMouseCol )
 nPointer := ;
    DC_SCRLHMOU( 0, 79, 24, nMouseCol, 1, LEN(aFields )

 ? aFields[nPointer]

Files:

_DCSCRL.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_scrlhbar()
   dc_scrlvbar()


dc_scrlvbar()

Display a vertical scroll bar

DC_SCRLVBAR() is used to display a vertical scroll bar on the screen to show the relative position of an array pointer within the array or the relative position of a numeric pointer between minimum and maximum selectable values.

Syntax:

DC_ScrlVBar( <nStartRow>, ;
             <nEndRow>, ;
             <nColumn>, ;
             <nCurVal>, ;
             <nMinVal>, ;
             <nMaxVal> ) -> nRowPointer

Returns:

 The row position of the scroll-bar.

Arguments:

<nStartRow> is the start display row.

<nEndRow> is the end display row.

<nColumn> is the display column.

<nCurVal> is the current value.  This could be an array
element.

<nMinVal> is the minimum value.  If an array, then this
should be 1 or the minimum selectable value.

<nMaxVal> is the maximum value.  If an array, then this
should be the number of items in the array or the maximum
selectable value.

Examples:

 aFields := array(fcount())
 aFields( aFields )     // create an array of field names
 nPointer := 10
 // display scroll bar showing relative position
 DC_SCRLVBAR( 0, 24, 79, nPointer, 1, LEN(aFields )

Files:

_DCSCRL.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_scrlvmou()
   dc_scrldmou()


dc_scrlvmou()

Return an array pointer from vertical scroll-bar mouse-click

DC_SCRLVMOU() is used with a vertical scroll bar on the screen to return an array pointer based on the relative mouse-click position within the scroll bar.

Syntax:

DC_ScrlVMou( <nStartRow>, ;
             <nEndRow>, ;
             <nMouseRow>, ;
             <nMinVal>, ;
             <nMaxVal>, ;
             <nCurrVal>, ;
             [<lPageMode>] ) -> nPointer

Returns:

 A pointer to an array element.

Arguments:

<nStartRow> is the start display row.

<nEndRow> is the end display row.

<nMouseRow> is the clicked mouse row.

<nMinVal> is the minimum value.  If an array, then this
should be 1 or the minimum selectable value.

<nMaxVal> is the maximum value.  If an array, then this
should be the number of items in the array or the maximum
selectable value.

<nCurrVal> is the current value.  This is needed to
determine the relative position of the mouse with respect
to the current position.

<lPageMode> if .TRUE. (default) will return a value that
is one page higher than <nCurrVal> if the mouse is clicked
below the current pointer or a value that is one page
lower than the <nCurrVal> if the mouse is clicked above
the current pointer.  If <lPageMode> is .FALSE. then the
value returned is a number proportional to the mouse-click
position within the scroll-bar region.

Examples:

 aFields := array(fcount())
 aFields( aFields ) // create an array of field names

 // get an array element based on mouse position
 dc_mougetpos( @nMouseRow, @nMouseCol )
 nPointer := ;
    DC_SCRLVMOU( 0, 24, 79, nMouseRow, 1, LEN(aFields )

 ? aFields[nPointer]

Files:

_DCSCRL.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_scrlvbar()
   dc_scrldmou()


dc_scrn2clipboard()

Capture current dialog screen to the ClipBoard

DC_Scrn2ClipBoard() will create a bitmap of the current dialog window that is in focus and copy the bitmap to the ClipBoard.

Syntax:

DC_Scrn2ClipBoard( [<oXbp>] ) -> nil

Returns:

NIL.

Arguments:

<oXbp>, is passed is the object who's image is to be transferred
to the clipboard.  If <oXbp> is not passed, then the entire
screen is transferred to the clipboard.

Examples:

SetAppFocus(AppDeskTop())
DC_Scrn2ClipBoard()

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_printclipboard()


dc_search()

Search all fields in a set of databases for a value

DC_SEARCH() is used to search all fields of specified work areas for matching text and list all occurences of found text.<br><br> The output can be sent to the screen, printer or a file and all occurrences where the text is found will be listed as follows:<br><br> File Record Field Text ----------- ------ ------------ --------------------------- CUSTOMER 123 PHONE 714-555-1212 MAILLIST 23567 PHONE_NUM (619)555-1212<br><br>

Syntax:

dc_search ( [<cFileName>], ;
            [<cText>], ;
            [<cOutput>] ) -> nil

Returns:

 Nil.

Arguments:

<cFileName> is the name of the database to search.  If no path
is given then the current SET DEFAULT directory is assumed.  If
<cFileName> is "ALL", then all databases that match the
currently selected RDD will be searched.  If no argument is
passed then a GUI dialog will be displayed prompting for a
file name, text and output.

<cText> is the text to search for.  This is a case
non-sensitive search and the first occurrence of the text in
each field will be listed.  If no argument is passed then a
GUI dialog will be displayed prompting for a file name, text
and output.

<cOutput> is the name of the output device.  If no argument is
given or <cOutPut> is a null "" string then the output will go
to the screen. If <cOutPut> = 'PRN' then the output will go to
the printer, otherwise the output will go to a file named
<cOutPut>.  If no extension is included then .PRN is assumed.
The file will be created in the SET DEFAULT directory.

Examples:

 // search CUSTOMER.DBF for occurrences of "O'BRIEN"
 // and display results on screen
 set rdd to 'DBFNTX'
 DC_SEARCH( 'CUSTOMER', "O'BRIEN" )

 // search CUSTOMER.DBF for occurrences of "O'BRIEN"
 // and copy results to file OBRIEN.TXT
 set rdd to 'DBFNTX'
 DC_SEARCH( 'CUSTOMER', "O'BRIEN", "OBRIEN" )

 // search all .DBF's for occurences of "CLIPPER"
 set rdd to 'DBFNTX'
 DC_SEARCH( 'ALL', 'CLIPPER' )

Files:

_DCSRCH.PRG, DCLIP2.DLL

See Also:


dc_seeklast()

Seek the last occurence of a key in the current index

DC_SeekLast() will perform a seek for the last key in the current index order that matches the passed in search key. If the key is not in the index, the function will position the table at EOF and set the found flag to False.

Syntax:

DC_SeekLast( <cKey> ) -> lFound

Returns:

A logical .TRUE. if the index key was found, .FALSE. otherwise.

Arguments:

<cKey> is the key to seek.

Files:

_DCAREA.PRG, DCLIP1.DLL

See Also:

   dc_dbseek()


dc_sendmailtodefault()

Send an email using the default Mail Client

DC_SendMailToDefault() is used to send an email using the default email client.<br><br>

Syntax:

DC_SendMailToDefault( <cTo>, ;
                      <cCC>, ;
                      <cSubject>, ;
                      <cBody> ) -> nil

Arguments:

<cTo> is the TO email address.

<cFrom> is the FROM email address.

<cSubject> is the SUBJECT of the email.

<cBody> is the BODY of the email.

Files:

_DCFUNCT.PRG


dc_setappfocus()

Set Focus to a specified object

DC_SetAppFocus is a replacement for SetAppFocus() that automatically walks up the parent tree and first maximizes all parent tabpages as required to insure that the tab pages are visible before the object receives focus.<br><br>

Syntax:

DC_SetAppFocus( <oXbp> ) -> oOldFocus

Returns:

A pointer to the previous object that had focus.

Arguments:

<oXbp> is the object that is to receive focus.

Files:

_DCFUNCT.PRG, DCLIPX.DLL


dc_setcpu()

Sets the next CPU to use on a multi-processor computer

DC_SetCpu() is used to assign the next CPU to be used by the application. Each time DC_SetCpu() is called (at the beginning of a program) it stores that information to a file, so it can be read later and automatically provide equal load balancing of the application.<br><br>This function is intended to be used on application servers such as Terminal Server or Citrix where the application would be running multiple times.<br><br>

Syntax:

DC_SetCpu( <nCPUs>, <cFile> ) -> nil

Returns:

Nil.

Arguments:

<nCPUs> is a number representative of the number of CPUs on the computer.
The default is 15 (4 CPUs).

Use 15 if 4 CPUs
Use  8 if 3 CPUs
Use  3 if 2 CPUs
Use  1 if 1 CPU

<cFileName> is the name of the text file that will contain the number of
the last CPU used.  The next CPU will automatically be assigned and this
number will be written into the file.

The default file name is GetEnv('WINDIR') + '\temp\setcpu.smp'

Examples:

// put this at the beginning of your main program

DC_SetCpu()

Files:

_DCFUNCT.PRG, DCLIPX.DLL


dc_setdaterange()

Set the valid date range for all Date GETS

DC_SetDateRange() is used to establish the valid range of dates for dates entered into GETS when using the @..DCSAY..GET or the @..DCGET commands.<br><br>If the entered date does not fall within the specified range, then an error message will be displayed.

Syntax:

DC_SetDateRange( [<aDates>] ) -> aOldDates

Returns:

An Array.

Arguments:

<aDates> is an array of 2 elements.  Both elements must be a
date type variable.  Element 1 must have a date that is less
than or equal to Element 2.

Files:

_dcgetbx.prg, dclipx.lib, dclipx.dll

See Also:

   @ DCSAY GET
   @ DCGET


dc_setdclip()

Set the directory to use for dCLIP data-dictionary files

DC_SETDCLIP() is used to establish the directory which will be searched for creating dCLIP DC*.DBF databases and indexes. If the files do not exist in this directory then they will be created. dCLIP establishes the default for this value in the following order:<br><br> 1. Uses the value in any SET DCLIP=<directory> statement in the DOS environment.<br><br> 2. Uses the directory in which the .EXEcutable program resides.

Syntax:

DC_SetDclip ( [<cPathSpec>] ) -> cPathSpec

Returns:

 A character string.

Arguments:

<cPathSpec> is any valid directory which may also include a
drive letter.  If no parameter is passed, then the value will
not be changed.

Notes:

Examples:

Files:
_DCGETE.PRG/.OBJ, DCLIPX.LIB


dc_setdefault()

Set the DEFAULT directory the right way

DC_SETDEFAULT() is used to set the system DEFAULT directory without the possibility of creating a runtime error. An invalid directory cannot be set and the \ is automatically appended to the end of the DEFAULT setting to insure that Clipper properly finds the files.

Syntax:

DC_SetDefault ( <cPath> ) -> cPath

Returns:

 The new DEFAULT setting.

Arguments:

<cPath> is the name of the directory.

Examples:

#include 'set.ch'

PROCEDURE Xtest()

DC_Gui(.t.)

DC_SETDEFAULT('C:\EXPRESS\SAMPLE')

DC_MsgBox({'Default directory is',;
           '',;
           SET(_SET_DEFAULT)})

DC_SETDEFAULT('C:\BOOGIE\MAN')

RETURN

Files:

_DCPATH.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_setdclip()


dc_setedit()

Pop up an editing screen for all SET environment variables

DC_SetEdit() is used to invoke a GUI editor for observing or modifying the value of any SET value in the environment.<br><br> The SET environment is the complete set of standard Xbase++ SETs such as SET EPOCH, SET DEFAULT, etc. and the additional eXPress++ SETs such as SET ODIR, SET PROMPT, etc.<br><br>

Syntax:

 DC_SetEdit( [<cSetName>] ) -> null string

Returns:

 A null string.

Arguments:

<cSetName> is the name of the SET environment variable to
edit.  If this parameter is not passed, then a picklist of all
environment variables will be displayed for editing.

Examples:

 . DC_SetEdit()
 . DC_SetEdit('DEFAULT')
 . DC_SetEdit('ODIR')

Files:

_DCSET.PRG, DCLIP2.DLL

See Also:

   SET


dc_setkeyactive()

Force DCREAD GUI dialogs to evaluate SET KEY code blocks

DC_SetKeyActive() is used to set a system flag which forces DC_ReadGui() dialogs which call DC_ReadGuiEventLoop() to react to a key that has been pressed which has been been established as a global "hot key" with the SET KEY command or SetKey() function. By default, system hot keys are ignored by the event handler. DC_SetKeyActive(.T.) will evaluate the associated code block when a hot key is pressed in the event loop just as it would if it were pressed in a standard text-mode READ.

Syntax:

DC_SetKeyActive( [<lActivate>] ) -> lOldActivate

Returns:

A logical value.

Arguments:

<lActivate> if .TRUE. will activate the Set Keys.

Examples:

DC_SETKEYACTIVE(.t)
SET KEY K_ALT_D TO {||DC_Dot()}
SET KEY K_AlT_B TO {||WebBrowser()}

DCREAD GUI

Files:

_DCGETBX.PRG, DCLIPX.DLL

See Also:

   dc_readgui()
   DCREAD


dc_setpointertree()

Set the mouse pointer on all objects in a tree

DC_SETPOINTERTREE() is used to change the mouse pointer for all objects in an object tree. This function walks down the :ChildList() tree and sets the mouse pointer on all children of the specified object.<br><br> Use this function to set an hourglass style pointer when performing operations that create a busy state.<br><br>

Syntax:

 DC_SetPointerTree ( <oXbp>,;
                     <cDllName>,;
                     <nPointer>,;
                     <nType> ) -> nil

Returns:

 Nil.

Arguments:

<oXbp> is the parent object.  For example, to insure that the
mouse pointer will be changed for all child objects in the current
application window, <oXbp> would be SetAppWindow().

<cDllName> is the name of the DLL that contains the mouse pointer.

<nPointer> is the resource number of the mouse pointer.  This
resource must exist in <cDllName> or be linked into the .EXE.

<nType> is the type of resource.

See the :setPointer() method of XbpWindow() in the Xbase++
documentation for more information.

Examples:

#include "dcdialog.ch"
#include "dccursor.ch"

PROCEDURE Xtest()

LOCAL GetList := {}, oDlg, GetOptions

@ 1,1 DCSAY "Please wait while packing file..."  SAYSIZE 40,2 ;
   FONT 'Helv.24.Bold'

DCGETOPTIONS ;
   NOMINBUTTON ;
   NOMAXBUTTON

DCREAD GUI FIT EXIT OPTIONS GetOptions PARENT @oDlg

DC_SetPointerTree( oDlg, nil, POINTER_BUSY_1, 1 )

DC_Pause(5)

oDlg:Destroy()

RETURN

Files:

_DCMOUSE.PRG/.OBJ, DCLIPX.LIB


dc_setpopkey()

Set or the return the value of the POPUP hot key

DC_SetPopKey() is used to change the hot key that is used to evaluate the POPUP code block when in a DCGET. The default key is xbeK_CTRL_ENTER.<br><br>

Syntax:

DC_SetPopKey( [<nHotKey>] ) -> nOldHotKey

Returns:

A numeric value.

Arguments:

<nHotKey> is the numeric xbeK_* value to assign.

Examples:

DC_SetPopkey( xbeK_CTRL_P )

Files:

_DCGETBX.PRG, DCLIPX.DLL

See Also:

   @ DCGET


dc_setproperty()

Set the property of a Getlist item associated with an object

DC_SETPROPERTY() is used to set a specified property in the GetList that is associated with an object.<br><br> <br><br>

Syntax:

DC_SetProperty ( <oXbp>, ;
                 <nProperty>, ;
                 <xValue> ) -> nil

Returns:

 Nil.

Arguments:

<oXbp> is a pointer to any object that was created by DC_ReadGui().

<nProperty> is a numeric value defined in DCDIALOG.CH.  See
DIALOG GETLIST for a definition of these manifest constants.

<xValue> is the value to store in the GetList item that is
associated with the object.

Examples:

 -- Example 1 --

 #include 'dcdialog.ch'

 PROCEDURE XTest()

 @ 1,1 DCPUSHBUTTON CAPTION 'Testing' SIZE 10,1 ;
       ACTION {|o|SetHelpCode(o,'BUTTON.TESTING')}

 DCREAD GUI FIT ADDBUTTONS

 RETURN nil

 * -------------

 STATIC FUNCTION SetHelpCode( oXbp, cHelpCode )

 DC_SetProperty( oXbp, cGETLIST_HELPCODE, cHelpCode )

 RETURN nil

Files:

_DCGETBX.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_getproperty()
   dc_getobject()
   DIALOG GETLIST


dc_setregion()

Crop a Dialog window to a specified shape

DC_SetRegion() is used to crop a dialog window to specified irregular shape. DC_SetRegion() accepts an array of coordinates that conforms to the specification for the "SetWindowRgn" API function of Windows in USER32.DLL.<br><br>

Syntax:

DC_SetRegion( <oDlg>, ;
              <aRegion> ) -> Nil

Returns:

Nil.

Arguments:

<oDlg> is an XbpDialog() object that has already been created.
It may also be any object which is derived from XbpDialog().

<aRegion> is an array of coordinates used to crop the perimeter
of the dialog window.

Examples:

oDlg := XbpDialog():new(AppDeskTop(),,{0,0},{100,100})
oDlg:create()
aRegion := DC_RegionArray( DCGUI_REGION_OCTAGON, 100 )
DC_SetRegion( oDlg, aRegion )

Files:

_DCCLASS.PRG, DCLIPX.DLL

See Also:

   dc_regionarray()
   dc_setregionellipse()
   @ DCPUSHBUTTON


dc_setregionellipse()

Crop a Dialog window to an ellipse/circle shape

DC_SetRegionEllipse() is used to crop a dialog window to the shape of an ellipse or circle. DC_SetRegionEllipse() accepts an array of coordinates that conforms to the specification for the "SetWindowRgn" API function of Windows in USER32.DLL.<br><br>

Syntax:

DC_SetRegionEllipse( <oDlg>, ;
                     <aRegion> ) -> Nil

Returns:

Nil.

Arguments:

<oDlg> is an XbpDialog() object that has already been created.
It may also be any object which is derived from XbpDialog().

<aRegion> is an array of coordinates used to crop the perimeter
of the dialog window.

Examples:

oDlg := XbpDialog():new(AppDeskTop(),,{0,0},{100,100})
oDlg:create()
aRegion := DC_RegionArray( DCGUI_REGION_ELLIPSE, 100 )
DC_SetRegion( oDlg, aRegion ) // crop to circle

oDlg := XbpDialog():new(AppDeskTop(),,{0,0},{100,100})
oDlg:create()
aRegion := DC_RegionArray( DCGUI_REGION_ELLIPSE, 100, 75 )
DC_SetRegion( oDlg, aRegion ) // crop to ellipse

Files:

_DCCLASS.PRG, DCLIPX.DLL

See Also:

   dc_regionarray()
   dc_setregion()
   @ DCPUSHBUTTON


dc_setrelation()

Set a relation with a child scope

DC_SETRELATION() is a front-end to the Xbase++ function dbSetRelation() whic defines a link between two work areas. The dependent or child work area is specified by the argument <cAlias> The controlling or parent work area is determined by the alias operator. If the alias operator is not used, the current work area is the parent work area the child area is synchronized with. Existing links in the parent work area are not deleted by DC_SetRelation(). <br><br>The synchronization of the record pointer in the child work area occurs using the return value of <bRelation> . The child work area is automatically searched for this value using DbSeek() anytime the record pointer in the parent work area changes. If no index is active in the child work area, synchronization is done using the function DbGoto(). This means that an attempt is made to set the record pointer in the child work area using the value returned from <bRelation> as a record ID. <br><br>The range for navigating the record pointer in the child work area can be restricted to a subset of records by specifying .T. (true) for the optional parameter <lSetScope> . In this case, only those records are accessible in the child work area where the link expression <bRelation> results in the same value for both work areas. When attempting to move the record pointer in the child work area outside this defined range, either Bof() or Eof() is set to .T. (true). In this way, a time consuming filter expression can be avoided. <br><br>

Syntax:

dc_setscope ( <cAlias>, ;
              <bRelation>, ;
              [<cRelation>], ;
              [<lSetScope>] ) -> xValue

Returns:

 The current SCOPE value.

Arguments:

<cAlias> is a character string containing the alias name for the
work area to which a link is defined.

<bRelation> is a code block containing an expression used to
position the record pointer in the child work area in order to
synchronize it with the record pointer in the parent work area.
The return value of <bRelation> is passed to DbSeek() to position
the record pointer in the child work area.

<cRelation> optionally specifies the link expression of <bRelation>
as a character string. This argument is used for the return value
of the function DbRelation() to determine the link expression. If
<cRelation> is not specified, the function DbRelation() returns a
null string ("").

<lSetScope> if .TRUE. (default) will automatically set the scope
in the child work area to the value of the data in the parent work
area whenever the parent record pointer is changed.

Notes:

With the exception of COMIX and Advantage Server, DC_SETSCOPE() does not establish the scoping range at the DBE-layer level, but instead stores the scoping information in dbCargo() as an array.

The scoping information is retrieved by record navigation functions such as DC_DBGOTOP(), DC_DBGOBOTTOM() and DC_DBSKIP().

Files:

_DCSCOPE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_setscope()


dc_setrest()

Restore the SET environment from a file

DC_SetRest() is used to restore the values of all Xbase++ and eXPress++ environment variables from a file previously created by DC_SetSave() or SAVE SET.<br><br> The SET environment is the complete set of standard Xbase++ SETs such as SET EPOCH, SET DEFAULT, etc. and the additional eXPress++ SETs such as SET ODIR, SET PROMPT, etc.<br><br>

Syntax:

 DC_SetRest( <cFileName> ) -> lStatus

Returns:

 A logical .TRUE. if the environment was successfully restored.

Arguments:

<cFileName> is the name of the file previously created by
DC_SetSave() or SAVE SET.  If no extension is given then the
extension .DCA will be added.

Examples:

 . SAVE SET TO MYFILE.SET
 . DoSomethingThatChangesEnvironment()
 . DC_SetRest('MYFILE.SET')

Files:

_DCSET.PRG, DCLIP2.DLL

See Also:

   dc_setsave()


dc_setroundrectregion()

Crop a Dialog window to round the corners to a specified radius

DC_SetRoundRectRegion() is used to crop a dialog window to round the corners to a specified radius.<br><br><br><br>

Syntax:

DC_SetRoundRectRegion( <oXbp>, ;
                       <nRadius> ) -> Nil

Returns:

Nil.

Arguments:

<oXbp> is any Xbp*() object that has already been created. The
object must be derived from XbpDialog() or XbpWindow().

<nRadius> is the amount of corner radius.  Default is 10.

Examples:

oDlg := XbpDialog():new(AppDeskTop(),,{0,0},{100,100})
oDlg:create()

DC_SetRoundRectRegion( oDlg, 15 )

Files:

_DCCLASS.PRG, DCLIPX.DLL

See Also:

   dc_setregion()


dc_setsave()

Save the SET environment to a file

DC_SetSave() is used to save the values of all Xbase++ and eXPress++ environment variables to a file to be later restored by DC_SetRest() or RESTORE SET.<br><br> The SET environment is the complete set of standard Xbase++ SETs such as SET EPOCH, SET DEFAULT, etc. and the additional eXPress++ SETs such as SET ODIR, SET PROMPT, etc.<br><br>

Syntax:

 DC_SetSave( <cFileName> ) -> lStatus

Returns:

 A logical .TRUE. if the file was successfully created.

Arguments:

<cFileName> is the name of the file to create.  If no extension
is given then the extension .DCA will be added.

Examples:

 . DC_SetSave('MYFILE.SET')

Files:

_DCSET.PRG, DCLIP2.DLL

See Also:

   dc_setrest()


dc_setscope()

Set a scoping value for the current work area

DC_SETSCOPE() is used to set a SCOPE TOP and SCOPE BOTTOM value for establishing a "scoping range" for a work area. The eXPress++ browsing and editing systems use DC_SETSCOPE() to store the scoping range when browsing and editing records. When a scoping range is set, only the records that fall within the range will appear in the browse or edit screens.<br><br>

Syntax:

dc_setscope ( <nWhich>, ;
              [<xValue>] ) -> xValue

Returns:

 The current SCOPE value.

Arguments:

<nWhich> is a number 0 if setting the SCOPE TOP value or a
number 1 if setting the SCOPE BOTTOM value.

<xValue> is the value to set.  This should be a value that
matches the current index key.  If <xValue> is a NIL then
the current setting will be returned.

DC_SetScope() functions just like COMIX CMXSetScope() and
Advantage's AX_SetScope(). For example, to include everything
starting with DC_G to DC_K, set the scope as follows:

DC_SetScope(0,'DC_G')

DC_SetScope(1,'DC_K')

To include everything starting with DC_G to DC_J, set the
scope as follows:

DC_SetScope(0,'DC_G')

DC_SetScope(1,'DC_K ') <- note the space

Notes:

With the exception of Advantage Server, DC_SETSCOPE() does not establish the scoping range at the DBE-layer level, but instead stores the scoping information in dbCargo() as an array.

The scoping information is retrieved by record navigation functions such as DC_DBGOTOP(), DC_DBGOBOTTOM(), DC_DBSKIP(), DC_BOF() and DC_EOF().

If the ADSDBE (Advantage Server) driver is being used, then DC_SetScope() simply calls AX_SetScope().

Examples:

 #include 'dcdialog.ch'
 #include 'appevent.ch'

 PROCEDURE XTest()

 LOCAL GetList := {}, oBrowse, aPres, cScopeTop, cScopeBot

 USE ..\XDOC\EXPRESS INDEX ..\XDOC\EXPRESS.CDX ;
     VIA FOXCDX ALIAS XDOC

 OrdSetFocus('COMMAND')
 DC_KeyStat(.t.)
 DC_SETSCOPE(0,'DC_G')
 DC_SETSCOPE(1,'DC_K')
 DC_DbGoTop()

 aPres := ;
  { { XBP_PP_COL_HA_FGCLR, GRA_CLR_WHITE },    /*  Header FG Color  */ ;
    { XBP_PP_COL_HA_BGCLR, GRA_CLR_DARKGRAY }, /*  Header BG Color  */ ;
    { XBP_PP_COL_DA_ROWSEPARATOR, XBPCOL_SEP_DOTTED }, /* Row Sep  */  ;
    { XBP_PP_COL_DA_COLSEPARATOR, XBPCOL_SEP_DOTTED }  /* Col Sep  */  ;
  }

 cScopeTop := Pad('DC_G',10)
 cScopeBot := Pad('DC_K',10)

 @ 1,1 DCSAY 'Scope Top' GET cScopeTop PICT '@!' SAYRIGHT ;
   VALID {||DC_SETSCOPE(0,Alltrim(cScopeTop)),;
            oBrowse:RefreshAll(),;
            SetAppFocus(oBrowse),.t.}

 @ 1,25 DCSAY 'Scope Bottom' GET cScopeBot PICT '@!'  SAYRIGHT ;
   VALID {||DC_SETSCOPE(1,Alltrim(cScopeBot)),;
            oBrowse:RefreshAll(),;
            SetAppFocus(oBrowse),.t.}

 @ 1, 65 DCPUSHBUTTON CAPTION 'Clear ~Scope' SIZE 10,1.5 ;
   ACCELKEY xbeK_ALT_S ;
   ACTION {||DC_ClrScope(),oBrowse:RefreshAll(),;
             SetAppFocus(oBrowse)}

 @ 3,1 DCBROWSE oBrowse ALIAS 'XDOC' ;
   SIZE 77,11.8 ;
   FREEZELEFT {1} ;
   PRESENTATION aPres ;
   SCOPE

 DCBROWSECOL FIELD XDOC->command ;
   HEADER "Command" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->type  ;
   HEADER "Type" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->short ;
   HEADER "Short Description" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->module ;
   HEADER "Module" PARENT oBrowse ;

 DCBROWSECOL FIELD XDOC->category ;
   HEADER "Category" PARENT oBrowse

 DCBROWSECOL FIELD XDOC->see_also ;
   HEADER "See Also" PARENT oBrowse

 DCREAD GUI ;
   FIT ;
   ADDBUTTONS ;
   TITLE 'Scoping Demo: DC_G thru DC_K'

 RETURN

Files:

_DCSCOPE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_clrscope()


dc_setscopearray()

Set a scoping value for the current work area using an array

DC_SETSCOPEARRAY() is used to create a "roll-your-own" style of scope on a database. It is much better than filters or scopes when needing to browse a subset of a large database. An "array" of record numbers is used to establish the scope and all DC_Db*() functions will respect the scope including @..DCBROWSE.<br><br><br><br>

Syntax:

dc_setscopearray ( <aRecords> | NIL ) -> aRecords

Returns:

The current scope array or a NIL>

Arguments:

<aRecords> is an array of record numbers.  If <aRecords> is a
NIL, then the scope is cleared.

<aRecords> may be a single-dimensional array or an optional
multi-dimensional array. If it is a multi-dimensional array then
the first element must be the numeric record number.

Notes:

With the exception of Advantage Server, DC_SETSCOPE() does not establish the scoping range at the DBE-layer level, but instead stores the scoping information in dbCargo() as an array.

The scoping information is retrieved by record navigation functions such as DC_DBGOTOP(), DC_DBGOBOTTOM(), DC_DBSKIP(), DC_BOF() and DC_EOF().

If the ADSDBE (Advantage Server) driver is being used, then DC_SetScope() simply calls AX_SetScope().

Examples:

USE TICKETS INDEX TICKETS
OrdSetFocus('DATE')
dbSeek(Date())
aRecords := {}
DO WHILE TICKETS->date == Date()
  IF TICKETS->time = '10:00' .OR. TICKETS->time = '11:00'
    AAdd(aRecords,TICKETS->(RecNo())
  ENDIF
  SKIP
ENDDO
DC_SetScopeArray(aRecords)
DC_DbGoTop()
@ .. DCBROWSE ALIAS 'TICKET'

Files:

_DCSCOPE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_setscope()


dc_spawnurl()

Spawn the program associated with a file name or URL

DC_SpawnURL() is used to spawn the program associated with a file name or URL.

Syntax:

DC_SpawnURL( <cURL>, ;
             [<lBackground>], ;
             [<lAsync>] ) -> nil

Returns:

Nil.

Arguments:

<cURL> is a URL or file name.

<lBackground> if .TRUE. will cause the spawned program to be
placed in the background, otherwise it will be placed in the
foreground.  The default is .FALSE. (foreground).

<lAsync> if .TRUE. will cause the spawned program to be run
asynchronously.  The default .FALSE.

Examples:

// Run Acrobat and view document.pdf
DC_SpawnURL( 'C:\DOCS\DOCUMENT.PDF' )

// Run Internet Explorer and navigate to website
DC_SpawnURL( 'http://donnay-software.com' )

Files:

_DCFUNCT.PRG,DCLIPX.DLL


dc_sqlconnection()

Make a SQL connection via SQLexpress

DC_SQLConnection() establishes a connection to an ODBC device via SQLexpress. If the SQLXPP.DLL is not statically linked to the application, it will be dynamically loaded.<br><br>DC_SQLConnection() tests for an already existing connection in the current thread. If there was a previous connection made, then a pointer to the connection object is returned, otherwise a new connection is made and the new connection object is returned.<br><br>The connection string used to connect is derived from a call to DC_ConnectString().<br><br>When a thread terminates, the SQL connection is automatically destroyed.

Syntax:

DC_SQLConnection( [<nType>] ) -> oConnection

Returns:

A connection object of type SQLConnection.

Arguments:

<nType> is a value defined in DCDIALOG.CH:

DCSQL_CONNECT_TYPE_READONLY
DCSQL_CONNECT_TYPE_READWRITE  * (default)

Examples:

oConnection := DC_SQLConnection()

Files:

_DCSQL.PRG, DCLIPX.DLL

See Also:

   dc_sqlconnectstring()
   dc_sqlcursor()


dc_sqlconnectstring()

Get or Set a SQL connection string

DC_SQLConnectString() is a Get/Set function that establishes a SQL connect string to be used by DC_SQLConnection().<br><br>

Syntax:

DC_SQLConnectString( [<cConnect>] ) -> cConnect

Returns:

A connection string.

Arguments:

<cConnect> is a string containing either a connection string or
the name of an .INI file that contains the connection string.

If <cConnect> is empty and a previous call to DC_SQLConnectString()
was made, then the previously stored value will be returned.

If <cConnect> is a pointer to an .INI file, then the file will
be opened to obtain the connect string.  The .INI file should
contain the following information:

[DATABASE]
ConnStr=<Connect String>

If <cConnect> is empty and a previous call to DC_SQLConnectString()
was not made, then a file named DCSQL.INI will be used to
establish the connection string.

Examples:

DC_SQLConnectString( 'MYCONNECT.INI' )

oConnection := DC_SQLConnection()

Files:

_DCSQL.PRG, DCLIPX.DLL

See Also:

   dc_sqlconnection()


dc_sqlcursor()

Create a SQL cursor via SQLexpress

DC_SQLCursor() is a front-end to all the SQLexpress functions that return a SQL cursor. <br><br>

Syntax:

DC_SQLCursor( [<oConn>], ;
              [<nType>], ;
              [@<nSuccess>], ;
              [<cStatement>], ;
              [<bSQLParam>], ;
              [<aPrimaryKeys>], ;
              [<nMaxRows>], ;
              [<abAddCol>], ;
              [<bFilter>], ;
              [<lTrim>], ;
              [<lDateTimeAsDate>], ;
              [<cTableName>] ) -> oCursor

Returns:

An SQLexpress cursor object.

Arguments:

<oConn> is an SQL connection object previously created with
SQLConnection or DC_SQLConnection.  If this parameter is not
passed then the value returned by DC_SQLConnection() is the
default.

<nType> is the type of cursor to create.  See the SQLexpress
documentation for more information.

<nType> Description
------- ------------------------------------------------------
   0    SQLSelect() with a read/write dynamic cursor
   1    SQLSelect() with a read-only dynamic cursor
   2    SQLDataSet()
   3    SQLListColumnPrivileges()
   4    SQLListColumns()
   5    SQLListForeignKeys()
   6    SQLListPrimaryKeys()
   7    SQLListProcedureColumns()
   8    SQLListProcedures()
   9    SQLListSpecialColumns()
  10    SQLListStatistics()
  11    SQLListTablePrivileges()
  12    SQLListTables()
  13    SQLListTypeInfo()

@<nSuccess> is a numeric variable, passed by reference, to store
the value returned by the oCursor:execute() method.  See the
SQLexpress documention for more information.

<cStatement> is the SQL statement.  This is required only for
<nTypes> 1 thru 3.

<bSQLParam>, <aPrimaryKeys>, <nMaxRows>, <abAddCol>, <bFilter>,
<lTrim> and <lDateTimeAsDate> are used only with <nType> of 3.
See SQLDataSet() in the SQLexpress documentation for more
information.

Examples:

DC_SQLConnectString('MYCONNECT.INI')
oConn := DC_SQLConnection()
IF Valtype(oConn) # 'O'
  RETURN nil
ENDIF

cStatement := 'SELECT * FROM INVOICES'

oCursor := DC_SQLCursor(,,,cStatement)

@ 0,0 DCBROWSE oBrowse DATA oCursor SIZE 100,20

DCBROWSECOL DATA DC_SQLFieldBlock( oCursor, 'INV_NMBR' ) ;
  PARENT oBrowse WIDTH 10 HEADER 'Invoice #'

DCBROWSECOL DATA DC_SQLFieldBlock( oCursor, 'INV_DATE' ) ;
  PARENT oBrowse WIDTH 10 HEADER 'Date'

DCREAD GUI FIT

Files:

_DCSQL, DCLIPX.DLL

See Also:

   dc_sqlfieldblock()
   dc_sqlgetsetblock()
   dc_sqlsortblock()
   dc_sqlconnection()


dc_sqldataset()

Create a data subset from an existing SQL cursor

DC_SQLDataSet() is used to create a SQLexpress DataSet cursor as a subset of another cursor.<br><br>

Syntax:

DC_SQLDataSet( <oCursor>, ;
               <bFilter> ) -> oDataSet

Returns:

A SQLexpress SQLDataSet() object.

Arguments:

<oCursor> is an SQLexpress SQLSelect or SQLDataSet cursor.

<bFilter> is a code block that is evaluated to determined which
rows from the primary cursor are added to the new dataset.  The
code block must return a .TRUE. value.  A data array equal to
oDataSet:recordGet() (see SQLexpress documentation) is passed
to the code block for each row (record).

Examples:

DC_SQLConnection()
cStatement := 'SELECT * FROM INVOICES'

oCursor := DC_SQLCursor(,,,cStatement)

bFilter := {|a|a[4]==dTraderDate}

oDataSet := DC_SQLDataSet( oCursor, bFilter )

@ 0,0 DCBROWSE oBrowse DATA oDataSet

Files:

_DCSQL, DCLIPX.DLL

See Also:

   dc_sqlcursor()


dc_sqlfieldblock()

Create a code block for browsing an SQL field

DC_SQLFieldBlock() is used to create a code block for browsing a field in an SQL cursor created by SQLExpress or DC_SQLCursor().<br><br>

Syntax:

DC_SQLFieldBlock( <oCursor>, ;
                  <ncField> ) -> bField

Returns:

A code block.

Arguments:

<oCursor> is a SQL cursor returned by DC_SQLCursor().

<ncField> if a numeric is the field number in the SQL cursor, or
if a character string is the field name in the SQL cursor.

Examples:

DC_SQLConnectString('MYCONNECT.INI')
oConn := DC_SQLConnection()
IF Valtype(oConn) # 'O'
  RETURN nil
ENDIF

cStatement := 'SELECT * FROM INVOICES'

oCursor := DC_SQLCursor(,,,cStatement)

@ 0,0 DCBROWSE oBrowse DATA oCursor SIZE 100,20

DCBROWSECOL DATA DC_SQLFieldBlock( oCursor, 'INV_NMBR' ) ;
  PARENT oBrowse WIDTH 10 HEADER 'Invoice #'

DCBROWSECOL DATA DC_SQLFieldBlock( oCursor, 'INV_DATE' ) ;
  PARENT oBrowse WIDTH 10 HEADER 'Date'

DCREAD GUI FIT

Files:

_DCSQL.PRG, DCLIPX.DLL

See Also:

   dc_sqlgetsetblock()
   dc_sqlcursor()


dc_sqlgetsetblock()

Create a code block for editing an SQL field

DC_SQLFieldBlock() is used to create a code block for browsing a field in an SQL cursor created by SQLExpress or DC_SQLCursor().<br><br>

Syntax:

DC_SQLGetSetBlock( <oCursor>, ;
                   <ncField> ) -> bGetSet

Returns:

A code block.

Arguments:

<oCursor> is a SQL cursor returned by DC_SQLCursor().

<ncField> if a numeric is the field number in the SQL cursor, or
if a character string is the field name in the SQL cursor.

Examples:

DC_SQLConnectString('MYCONNECT.INI')
oConn := DC_SQLConnection()
IF Valtype(oConn) # 'O'
  RETURN nil
ENDIF

cStatement := 'SELECT * FROM INVOICES'

oCursor := DC_SQLCursor(,,,cStatement)

@ 0,0 DCBROWSE oBrowse DATA oCursor SIZE 100,20
      EDIT xbeBRW_ItemSelected

DCBROWSECOL DATA DC_SQLGetSetBlock( oCursor, 'INV_NMBR' ) ;
  PARENT oBrowse WIDTH 10 HEADER 'Invoice #'

DCBROWSECOL DATA DC_SQLGetSetBlock( oCursor, 'INV_DATE' ) ;
  PARENT oBrowse WIDTH 10 HEADER 'Date'

DCREAD GUI FIT

Files:

_DCSQL.PRG, DCLIPX.DLL

See Also:

   dc_sqlfieldblock()
   dc_sqlcursor()


dc_sqlsortblock()

Create a code block for sorting an SQL column

DC_SQLSortBlock() is used to create a code block for sorting a column in an SQL cursor created by SQLExpress or DC_SQLCursor().<br><br>

Syntax:

DC_SQLFieldBlock( <oCursor>, ;
                  <ncField>, ;
                  [@<nColumn>] ) -> bSort

Returns:

A code block.

Arguments:

<oCursor> is a SQL cursor returned by DC_SQLCursor().

<ncField> if a numeric is the field number in the SQL cursor, or
if a character string is the field name in the SQL cursor.

@<nColumn> is a numeric value, passed by reference, to store
the numeric field position of field in the SQL cursor whenever
the codeblock is evaluated.

Examples:

DC_SQLConnectString('MYCONNECT.INI')
oConn := DC_SQLConnection()
IF Valtype(oConn) # 'O'
  RETURN nil
ENDIF

cStatement := 'SELECT * FROM INVOICES'

oCursor := DC_SQLCursor(,,,cStatement)

@ 0,0 DCSAY {||'Sorted by: ' IIF(nColumn=1,'Invoice #','Date')} ;
      SAYSIZE 10

@ 1,0 DCBROWSE oBrowse DATA oCursor SIZE 100,20

DCBROWSECOL DATA DC_SQLFieldBlock( oCursor, 'INV_NMBR' ) ;
  PARENT oBrowse WIDTH 10 HEADER 'Invoice #'
  SORT DC_SQLSortBlock( oCursor, 'INV_NMBR', @nColumn )

DCBROWSECOL DATA DC_SQLFieldBlock( oCursor, 'INV_DATE' ) ;
  PARENT oBrowse WIDTH 10 HEADER 'Date'
  SORT DC_SQLSortBlock( oCursor, 'INV_DATE', @nColumn )

DCREAD GUI FIT

Files:

_DCSQL.PRG, DCLIPX.DLL

See Also:

   dc_sqlfieldblock()
   dc_sqlcursor()


dc_status()

Display System status window

DC_Status() is used to display a scrollable window of information about the system application.<br><br>

Syntax:

 DC_Status( [<cFileName>], ;
            [<lAppend>], ;
            [<lWindow>], ;
            [<lWorkAreas>] ) -> NIL

Returns:

 Nil.

Arguments:

<cFileName> is an optional name of a file to write the status.

<lAppend> if .TRUE. will append the status to end of
<cFileName> otherwise the file will be overwritten.

<lWindow> if .TRUE. (default) will display the status in a
window and the user can scroll up or down through the window to
observe any portion of the status.  The display will be
restored upon exiting the windoe.  If .FALSE. the status will
scroll up   the display and the user will be prompted to press
a key for each new screen.

<lWorkAreas> if .TRUE. will display only the status of the work
areas.  If .FALSE. (default) the status of the Xbase++ SET
environment variables and eXPress++ environment variables will
also be displayed.

Examples:

 . USE COLLECT INDEX COLLECT
 . DC_Status()

Files:

_DCSTAT.PRG, DCLIP2.DLL

See Also:

   DISPLAY STATUS


dc_str2ar()

Convert a string to a multidimensional array

DC_Str2Ar() will restore an array from a string that was previously created with DC_Ar2Str(). This set of functions is an alternative to using the Xbase++ functions Bin2Var() and Var2Bin() because they will create a runtime error if the array contains code blocks with non-persistent data.<br><br> If the array contains code blocks, the code blocks will be saved and restored provide that they contain persistent data. Any code block that contains non-persistent data will be restored as a NIL.<br><br> If the array contains pointers to objects, they pointers will be restored as a NIL.<br><br>

Syntax:

DC_Str2Ar ( <cString> ) -> aArray

Returns:

 A multidimensional array.

Arguments:

<cString> is a string previously created by DC_Ar2Str().

Examples:

 PROCEDURE XTest()

 LOCAL aDir

 aDir := Directory()

 USE dirs
 APPEND BLANK
 REPL DIRS->array WITH DC_Ar2Str(aDir)

 aDir := DC_Str2Ar(DIRS->array)
 DC_ArrayView(aDir)

 RETURN

Files:

_DCASAVE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_arestore()


dc_struupdate()

Modify the structure of a database

DC_STRUUPDATE() is used to update the structure of the current work area in the event that the database structure required by the program may be different from existing databases.<br><br> This function makes it easy to have your program automatically update the structure of existing databases in the event that fields have been added, deleted or re-sized. If you open your databases with DC_DBFILE() and pass it a structure array, then the databases will automatically be updated the first time the new program is run.<br><br><br><br>

Syntax:

 DC_StruUpdate ( <aStructure>, ;
                [<cNewFileName>], ;
                [<lChangedType>], ;
                [<lChangedName>], ;
                [<lPrompt>] ) -> lStatus

Returns:

 A logical .TRUE. if the file was successfully updated, .FALSE.
 if the operation was aborted by the user or otherwise failed.

Arguments:

<aStructure> is a multi-dimensional array with one sub-array
for each database field.  This may be a standard Clipper
structure array or an enhanced array with information about
previous field type(s) and field name(s).

 Element  Type   Description
 ------   ----   ------------------------
   [1]     C     Field Name
   [2]     C     Field Type
   [3]     N     Field Length
   [4]     N     Field Decimals
   [5]     C     Old Field Type (optional)
   [6]     C     Old Field Name (optional)
   [7]     X     Default Value for new fields (optional)
                 Must be same value as new field.

<cNewFileName> is the name of the new file to create.  If
parameter is not passed, then the new file will be given the
same name as the old file.

<lChangedType> if .TRUE. will use a "slower" method of update
to insure that data is properly restored.  Pass this flag if
the type of one or more fields has changed and the array
does not contain the old information (element 5).

<lChangedName> if .TRUE. will use a "slower" method of update
to insure that data is properly restored.  Pass this flag if
the name of one or more fields has changed and the array
does not contain the old information (element 6).

<lPrompt> if .TRUE. (default) will prompt the user with the
option of erasing the backup file(s) after the structure
update.  If .FALSE. the backup files will not be erased and
the user will not be prompted.

Examples:

 aStru := { ;
   { 'CUST_NAME','C',25,0 },;
   { 'CUST_NMBR','C',10,0 },;
   { 'LAST_DATE','D',8,0  } }

 use customer
 if .not. dc_isstru( aStru )
   DC_STRUUPDATE( aStru )
 endif

Files:

_DCSTRU.PRG, DCLIP2.DLL

See Also:

   dc_modstru()
   dc_dbfile()
   dc_isstru()


dc_strwrap()

Convert a string to a text array and specify line length

DC_STRWRAP() is used to convert a long text string to multiple lines of a specified length per line. This function is handy when text must fit within a specified width of a display or printout.

Syntax:

DC_StrWrap ( <cString>, ;
             <nLength> ) -> aText

Returns:

 An array of strings that contains the original <cString>
 information formatted to the length of <nLength>.

Arguments:

<cString> is a character string.

<nLength> is the length of each line in the output array.

Examples:

#include 'dcdialog.ch'

PROCEDURE Xtest()

LOCAL cString, aText, i

cString := 'The quick red fox jumped over the lazy dog.'
aText := DC_STRWRAP( cString, 10 )
for i := 1 to len(aText)
  DCQOUT aText[i]
next

RETURN

/*
 The quick
 red fox
 jumped
 over the
 lazy dog.
*/

Files:

_DCSTR.PRG/.OBJ, DCLIPX.LIB


dc_sum()

Sum numeric fields in selected database

DC_Sum() is used to sum numeric fields from the currently selected database based on a set of conditions. As GUI dialog window is displayed for the user to select the conditions.

Syntax:

 DC_Sum() -> lStatus

Returns:

 A logical .TRUE. if the sum was not aborted.

Arguments:

 None.

Examples:

 . USE COLLECT
 . DC_Sum()

Files:

_DCSUM.PRG, DCLIP2.DLL

See Also:

   SUM


dc_tabactivate()

Activate a Tab Page

DC_TabActivate() is used to select a TabPage by it's object name.

Syntax:

DC_TabActivate( <oTabPage>, ;
                [<lCompleteEvents>] ) -> nil

Returns:

Nil.

Arguments:

<oTabPage> is the tab page to activate.

<lCompleteEvents> will call DC_CompleteEvents() after activating
the tab.

Files:

_DCFUNCT.PRG

See Also:

   @ DCTABPAGE


dc_tabpagecolor()

Set the default tabpage minimized and maximized colors

DC_TabPageColor() is a Get-Set function that is used to automatically set the color of Maximized and Minimized Tabpages that have been created by the @ DCTABPAGE command, so that the currently selected tab may be a different color than unselected tabs.

Syntax:

DC_TabPageColor( [<aColors>] ) -> <aOldColors>

Returns:

An array containing the old colors.

Arguments:

<aColors> is a two-element array containing the minimized and
maximized colors respectively.  Each element is a sub-array containing
foreground and background colors.  Each sub-array is 2 elements
that are numeric GRA* values or a 3-element sub-array of RGB values.

Examples:

-- Example 1 (numeric values) ---

<aColors> := { { GRA_CLR_BLACK, GRA_CLR_WHITE }, ;
               { GRA_CLR_BLACK, GRA_CLR_YELLOW } }

DC_TabPageColor( aColors )

-- Example 2 (RGB values) ---

<aColors> := { { { 0,0,0 }, { 128, 128, 128 } }, ;
               { { 0,0,0 }, { 230, 127, 030 } } }

DC_TabPageColor( aColors )

See Also:

   @ DCTABPAGE


dc_tagallcreate()

Create index tags for all fields in a database

DC_TAGALLCREATE() is used to create an index tag for all fields (up to 99) in a database. This command is handy when you wish to have an index for each field in the database and are using the HUNT..RESUME .or DC_HUNT() "smart seeking" feature of eXPress++.<br><br>

Syntax:

 DC_TagAllCreate( [<cCDXName>], ;
                  [<aFields>], ;
                  [<nLength>] ) -> lStatus

Returns:

 A logical .TRUE. if the index is successfully created, .FALSE.
 otherwise.

Arguments:

<cCDXName> is the name of the Combined Index file to create.
If no extension is given, then if the default extension for
combined indexes supported by the Data driver in use will be
appended.

If no <cCDXName> name is given, then the index will be created
using the same prefix as the open database and with the default
extension for combined indexes supported by the Data driver in
use.

<aFields> is a list of index tag names to create.  The tag
name(s) must be the same as the name(s) of valid fields in the
current work area.  If no argument is passed then tags for ALL
fields will be created.

<nLength> is an optional argument only to determine the maximum
length of character type indexes.  For example, if you have a
character field of 100 bytes, you most likely will not want to
index on all 100 bytes, but instead on only the first 10
characters.  If this argument is not passed, then a default length
of 10 will be used. If the length of any character field is less
than <nLength> then the index length for that specific tag will be
the field length.

Examples:

 . USE MAILLIST VIA DBFCDX
 . DC_TAGALLCREATE('MAILLIST.CDX',{"LAST", "COMPANY", "SOURCE"} )
 . DC_Hunt( 'SCOTT' )

Files:

_DCTAGS.PRG, DCLIP2.DLL

See Also:


dc_tagdelete()

Delete a tag from a combined index

DC_TagDelete() is used to delete an index tag from a combined index.

Syntax:

 DC_TagDelete() -> lStatus

Returns:

 A logical .TRUE. if the index tag was deleted successfully,
 .FALSE. otherwise.

Arguments:

 None.

Examples:

 . USE EXPRESS INDEX EXPRESS.CDX EXCL
 . DC_TagDelete()

Files:

_DCTAGS.PRG, DCLIP2.DLL

See Also:

   DELETE TAG


dc_tagrecord()

Tag the current record or record group in a Browse

DC_RecTagToggle() is used to toggle the value of the record tag on the current record. If the record number exists in the tag array, then it will be removed, otherwise it will be added.<br><br><br><br>

Syntax:

 DC_TagRecord( <oBrowse>, ;
               <@nLastRec>, ;
               <@nLastPos> ) -> nil

Returns:

Nil.

Arguments:

<oBrowse> is a pointer to an XbpBrowse() or DC_XbpBrowse() object.

<nLastRec> and <nLastPos> are variables, passed by reference, to
store record pointer information.

Notes:

CAUTION: The eXPress++ tagging system is designed for ad-hoc tagging of records using simple menu selection and database commands. You will notice a gradual speed detioration as you add more records to the tag array when browsing. This is because the DC_TAGGED() function must scan more records in the array. It is recommend that you refrain from tagging more than 1000 records or you may experience unacceptable slowness during browsing.

If you need a tagging system that will support a much larger number of records, it is recommended that you add a TAG (logical) field to your database.

Examples:

See the Record Tagging example in XDEMO.EXE - Sample Group 6.

Files:

_DCRTAG.PRG, DCLIPX.DLL

See Also:

   dc_rectag
   dc_tagrecord()
   dc_rectagarray()


dc_tbinkey()

A special version of INKEY() for adding mouse to Tbrowse system

DC_TBINKEY() is used to easily convert existing Tbrowse systems to work with a mouse. In most case, simply replacing the call to INKEY() in the Tbrowse key input handler to a call DC_TBINKEY() is all that's required.

Syntax:

DC_TBInkey ( <oObject>, ;
             <nDelay>, ;
             [<aButtons>], ;
             [<aNavigate>], ;
             [<nStartRow>], ;
             [<nEndRow>] ) -> nInkeyVal

Returns:

 A numeric value equivalent to one of the following:

  a.  -101 if the mouse is clicked within the navigation region.

  b.  The INKEY value of any key pressed.

  c.  The value in <aButtons>, element #5 if the mouse is
      clicked in an <aButtons> region.

Arguments:

<oObject> is the name of the Tbrowse object to mouse.

<nDelay> is the amount of seconds to wait for a key click or
mouse click.  If zero, then wait forever.

<aButtons> is an optional multi-dimensional array of mouse-
buttons that must meet the criteria specified for the
DC_MOUSEKEY() function.  If the mouse is clicked within a
specified region the value returned by will be the key value
passed in the array.

<aNavigate> is an optional multi-dimensional array of mouse-
button coordinates to be used for navigation.  There are a
total of 10 sub-arrays required, each with 4 numeric elements
designating the coordinates on the screen.  If the mouse is
clicked within the specified coordinates, then the activity
will be performed.

Subarray  Description                         Default
--------  -----------                         ------------
   1      Pan Left  (same as K_CTRL_LEFT)     o:nLeft-1
   2      Pan Right (same as K_CTRL_RIGHT)    o:nRight+1
   3      Move up one Row (same as K_UP)      o:nTop+1
   4      Move down one Row (same as K_DOWN)  o:nBottom-1
   5      Page Up (same as K_PGUP)            o:nTop
   6      Page Down (same as K_PGDN)          o:nBottom
   7      Pan Home (same as K_CTRL_HOME)      Col 0
   8      Pan End (same as K_CTRL_END)        Col 79
   9      Top (same as K_CTRL_PGUP)           Row 0
  10      Bottom (same as K_CTRL_PGDN)        MaxRow()

If no array is passed, then the coordinates for the above
functions will be equivalent to the default values.

Note:  Due to Tbrowse limitations, DC_TBINKEY() calculates
the active area of the screen by scanning the columns in
the object to determine the number of heading and footing
rows.  This can slow down operation, therefore, to regain
speed it is recommended that you pass two parameters:

<nStartRow> - Starting data row (screen row)
<nEndRow> - Ending data row (screen row)

Examples:

 // Start of Tbrowse Key Check routine
 do while lastkey()#27
   do while !b:stabilize()
   enddo
   k := DC_TBINKEY(b,0,,,5,22)
   do case
     case k=K_DOWN
       b:down()
     case k=K_UP
       b:up()
     case k=K_PGDN
       b:pagedown()
     case k=K_PGUP
       b:pageup()
     case k=K_CTRL_PGUP
       b:gotop()
     case k=K_CTRL_PGDN
       b:gobottom()
     case k=K_RIGHT
       b:right()
     case k=K_LEFT
       b:left()
     case k=K_HOME
       b:home()
     case k=K_END
       b:end()
     case k=K_CTRL_LEFT
       b:panleft()
     case k=K_CTRL_RIGHT
       b:panright()
     case k=K_CTRL_HOME
       b:panhome()
     case k=K_CTRL_END
       b:panend()
   endcase
 enddo

Files:

_DCTBINK.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_inkey()
   dc_mousekey()


dc_testbof()

Test if record pointer is at top of file

DC_TESTBOF() is used to test whether or not the record pointer is at the first record in the file. This function works with scoped databases. <br><br>

Syntax:

DC_TestBof() -> lStatus

Returns:

 The actual number of records that were skipped.  This number may
 be less than the number of records requested in the event that
 the first or last record in the scoped group was encountered.

 DC_DBSKIP() will not skip past the bottom record or previous
 the top record in a scoped group.

Arguments:

 None.

Notes:

Files:

_DCSCOPE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_setscope()


dc_testeof()

Test if record pointer is at bottom of file

DC_TESTEOF() is used to test whether or not the record pointer is at the last record in the file. This function works with scoped databases. <br><br>

Syntax:

DC_TestEof() -> lStatus

Returns:

 The actual number of records that were skipped.  This number may
 be less than the number of records requested in the event that
 the first or last record in the scoped group was encountered.

 DC_DBSKIP() will not skip past the bottom record or previous
 the top record in a scoped group.

Arguments:

 None.

Notes:

Files:

_DCSCOPE.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_setscope()


dc_testlockenable()

A Get-set function to enable testing a lock when using DC_RecLock()

DC_TestLockEnable() is a Get-Set function that is used to enable a feature in DC_RecLock() and DC_AddRec() that writes to the record to insure that the lock was established. The write simply echoes back the value of the first field in the record.<br><br>The default is FALSE.

Syntax:

DC_TestLockEnable( <lSetting> ) -> <lOldSetting>

Returns:

A logical value.

Files:

_DCLOCK.PRG, DCLIPX.DLL

See Also:

   dc_reclock()
   dc_addrec()


dc_timetosec()

Convert a time string to seconds

DC_TimeToSec() is used to convert a time string in the format hh:mm:ss to a numeric seconds since midnight.

Syntax:

DC_TimeToSec( <cTimeString> ) -> <nSeconds>

Returns:

A numeric value.

Arguments:

<cTimeString> is a time string in the format hh:mm:ss.

Files:

_DCCALEN.PRG, DCLIPX.DLL


dc_token()

Extract a token from a string

DC_TOKEN() is used to extract a portion of a character string based on it's "token" position within the string.<br><br> Tokens are sub-strings within a string that are separated by common delimiters.

Syntax:

DC_Token ( <cString>, ;
           [<cDelims>], ;
           <nOccurence> ) -> cToken

Returns:

 A character string.

Arguments:

<cString> is a character string containing tokens.

<cDelims> is a character string containing the delimeter(s)
to use between tokens.  If no parameter is passed then the
following default set of delimeters will be used:

  <SPACE>
   Š,.;:!?/()#&%+-*
  <CHR(0)>
  <CHR(9)>
  <CHR(10)>
  <CHR(13)>
  <CHR(26)>

<nOccurence> is the number of the token to extract.

Examples:

 cString := 'This is a test'
 ? DC_TOKEN( cString,,2 )
 is

 cString := 'AB|CD|EF|GHI|JKLM|NOP|QR|STUVW|XYZ'
 ? DC_TOKEN( cString,'|',5 )
 JKLM

Files:

_DCTOKEN.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_tokenarray()


dc_tokenarray()

Parse all tokens in a string to an Array

DC_TOKENARRAY() is used to return an array of character strings derived from a single character string. Tokens are sub-strings within a string that are separated by common delimiters. The array returned will contain one element for each token in the string.

Syntax:

DC_TokenArray ( <cString>, ;
                [<cDelims>], ;
                [<lQuotes>] ) -> aTokens

Returns:

 A array of character strings.

Arguments:

<cString> is a character string containing tokens.

<cDelims> is a character string containing the delimeter(s)
to use between tokens.  If no parameter is passed then the
following default set of delimeters will be used:

  <SPACE>
   Š,.;:!?/()#&%+-*
  <CHR(0)>
  <CHR(9)>
  <CHR(10)>
  <CHR(13)>
  <CHR(26)>

If <lQuotes> is .TRUE. then delimiters that exist within quotes ""
are ignored and quotes are stripped.  Default is .FALSE.

  Example: cString := '"Donnay, Inc.",'"eXpress++"'

           DC_TokenArray(cString,',',.f.) ->
               returns {""Donnay", " Inc."", ""eXpress++""}

           DC_TokenArray(cString,',',.t.) ->
               returns {"Donnay, Inc.", "eXpress++"}

Examples:

 cString := 'AB|CD|EF|GHI|JKLM|NOP|QR|STUVW|XYZ'
 aTokens := DC_TOKENARRAY( cString,'|' )
 display array aTokens

 [1] C AB
 [2] C CD
 [3] C EF
 [4] C GHI
 [5] C JKLM
 [6] C NOP
 [7] C QR
 [8] C STUVW
 [9] C XYZ

Files:

_DCTOKEN.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_token()


dc_tokenjustify()

Perform text-justfication of tokens in a string

DC_TOKENJUSTIFY() is used to perform text justification of all tokens in a character string.<br><br> Tokens are sub-strings within a string that are separated by common delimiters.

Syntax:

DC_TokenJustify ( <cString>, ;
                  [<cDelims>], ;
                  <nWidth>, ;
                  <nType> ) -> cString

Returns:

 A character string.

Arguments:

<cString> is a character string containing tokens.

<cDelims> is a character string containing the delimeter(s)
to use between tokens.  If no parameter is passed then the
following default set of delimeters will be used:

  <SPACE>
   Š,.;:!?/()#&%+-*
  <CHR(0)>
  <CHR(9)>
  <CHR(10)>
  <CHR(13)>
  <CHR(26)>

<nWidth> is the final width of the resultant character
string.

<nType> is used to denote the type of justification to
perform:

   0 - Center Justify to fit <nWidth> characters
   1 - Pad Right until <nWidth> characters
   2 - Left Justify. Pad right to <nWidth> characters
   3 - Pad Left until <nWidth> characters
   4 - Right Justify. Pad left to <nWidth> characters

Examples:

 cString := 'This is a test'
 ? DC_TOKENJUSTIFY( cString,,50,0 )
 This            is             a            test

Files:

_DCTOKEN.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_token()
   dc_tokenarray()


dc_tokennum()

Determine the number of tokens in a string

DC_TOKENNUM() is used to determine the number of tokens that exist in a character string.<br><br> Tokens are sub-strings within a string that are separated by common delimiters.

Syntax:

DC_TokenNum ( <cString>, ;
              [<cDelims>] ) -> nTokens

Returns:

 A numeric value.

Arguments:

<cString> is a character string containing tokens.

<cDelims> is a character string containing the delimeter(s)
to use between tokens.  If no parameter is passed then the
following default set of delimeters will be used:

  <SPACE>
   Š,.;:!?/()#&%+-*
  <CHR(0)>
  <CHR(9)>
  <CHR(10)>
  <CHR(13)>
  <CHR(26)>

Examples:

 cString := 'This is a test'
 ? DC_Token( cString,,2 )
 is
 ? DC_NUMTOKEN( cString )
 4

 cString := 'AB|CD|EF|GHI|JKLM|NOP|QR|STUVW|XYZ'
 ? DC_Token( cString,'|',5 )
 JKLM
 ? DC_NUMTOKEN( cString )
 9

Files:

_DCTOKEN.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_token()
   dc_tokenarray()


dc_tooltipenable()

Enable or Disable Tooltip threads

DC_ToolTipEnable() is a Get-Set function that is used to enable or disable tooltip threads.<br><br>Each time DCREAD GUI or DC_ReadGui() is called, a tooltip thread is started to handle the displaying of tooltips. This thread is started only if there is at least one TOOLTIP defined in the GetList. DC_ToolTipEnable(.f.) will prevent the thread from starting.<br><br>

Syntax:

DC_ToolTipEnable( [<lEnable>] ) -> lOldSetting

Arguments:

<lEnable> if .TRUE. will enable tooltips, otherwise tooltips will
be disabled.

Files:

_DCGETBX.PRG, DCLIPX.DLL

See Also:

   dc_tooltiptimeout()


dc_tooltiptimeout()

Sets the timeout period for tooltips

DC_ToolTipTimeout is a Get-Set function that is used to cause tooltip messages to timeout after a specified amount of mouse inactivity. The default is 5 seconds. This should fix the problem of tooltips bleeding through other windows.

Syntax:

DC_ToolTipTimeout( [<nSeconds>] ) -> nOldSetting

Arguments:

<nSeconds> is the amount of seconds to display the tooltip.

Examples:

DC_ToolTipTimeOut(10) // 10 seconds

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_tooltipenable()


dc_translate()

Translate a command line to an array of Functions

DC_TRANSLATE() is a fully-recursive command translator that translates commands into an array of functions to be executed via the macro-compiler. DC_TRANSLATE() requires that the file DCSTD.CH exist in the INCLUDE path of the workstation. The DCSTD.CH file contains all the standard eXPress++ commands and pointers to the Xbase++ include files for the standard Xbase++ commands and defines.<br><br> If the command syntax entered matches a command in any of the loaded include files, then it will be converted to an array of character expressions.<br><br>

Syntax:

dc_translate ( <cCommandLine> ) -> aFunctions

Arguments:

<cCommandLine> is any command string that contains Xbase++
commands, eXPress++ commands or commands from pre-processor
include files which are part of <cCommandLine> or which are
defined in DCCUSTOM.CH.

Examples:

 accept "enter a command" to cCommand
 aFunctions := DC_TRANSLATE( cCommand )
 for i := 1 to len(aFunctions)
   cMacro := aFunctions[i]
   xDummy := &cMacro
 next

Files:

_DCTRAN1.PRG

See Also:

   dc_dot()
   dc_interpret()


dc_txtclose()

Close text file

DC_TXTCLOSE() is used to close a text file that was opened with DC_TXTOPEN().

Syntax:

DC_TxtClose ( <nHandle> ) -> lStatus

Returns:

 A logical .TRUE. if the file was successfully closed.

Arguments:

<nHandle> is the numeric file handle returned by DC_TXTOPEN().
Caution: This is NOT the dos file handle.

Examples:

 nHandle := dc_txtopen( 'dclip.sys' )
 do while !dc_txteof( nHandle )
   ? dc_txtline( nHandle )
   dc_txtskip( nHandle, 1 )
 enddo
 DC_TXTCLOSE( nHandle )

Files:

_DCTXT.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_txtopen()


dc_txtcount()

Return the number of lines in an open text file

DC_TXTCOUNT() is used to report the number of lines in a text file that was opened with DC_TXTOPEN().

Syntax:

DC_TxtCount ( <nHandle> ) -> nLines

Returns:

 A number value equal to the number of lines in the text file.

Arguments:

<nHandle> is the numeric file handle returned by DC_TXTOPEN().
Caution: This is NOT the dos file handle.

Examples:

 nHandle := dc_txtopen( 'dclip.sys' )
 if DC_TXTCOUNT( nHandle ) < 100
   do while !dc_txteof( nHandle )
     ? dc_txtline( nHandle )
     dc_txtskip( nHandle, 1 )
   enddo
   dc_txtclose( nHandle )
 endif

Files:

_DCTXT.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_txtopen()


dc_txteof()

Is file pointer at end of text file?

DC_TXTEOF() reports whether the file pointer is at the end of a text file that was opened with DC_TXTOPEN().

Syntax:

DC_TxtEof( <nHandle> ) -> lStatus

Returns:

 A logical .TRUE. if the file pointer is at the end of the text
 file, .FALSE. otherwise.

Arguments:

<nHandle> is the numeric file handle returned by DC_TXTOPEN().
Caution: This is NOT the dos file handle.

Examples:

 nHandle := dc_txtopen( 'dclip.sys' )
 do while !DC_TXTEOF( nHandle )
   ? dc_txtline( nHandle )
   dc_txtskip( nHandle, 1 )
 enddo
 dc_txtclose( nHandle )

Files:

_DCTXT.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_txtopen()


dc_txtfind()

Fast text search for a string within a text file

DC_TXTFIND() is used to find a string of text in a text file.<br><br> The search will be started at the current file pointer.<br><br>

Syntax:

 DC_TxtFind( <nHandle>, ;
             <cSearchString>, ;
            [<lCaseSensitive>] ) -> nFilePointer

Returns:

 The numeric position (byte pointer) where the text was found.
 If the text was not found, the value -1 will be returned and
 the pointer will be at the end of the file.

Arguments:

<nHandle> is the numeric file handle returned by DC_TXTOPEN().

<cSearchString> is the text to find.

<lCaseSensitive> if .TRUE. (default) will only find text that
exactly matches the case of <cSearchString>.

Examples:

 . nHandle := dc_txtopen( 'customer.txt' )
 . nFoundAt := DC_TXTFIND( nHandle, 'Jones' )
 . ? nFoundAt
67345

Files:

_DCTXT.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_txtopen()


dc_txtgoto()

Goto a specified line in a text file

DC_TXTGOTO() is used to go to a specified line of text in a text file that was opened with DC_TXTOPEN().

Syntax:

DC_TxtGoTo ( <nHandle>, ;
             <nLineNumber> ) -> nLinePointer

Returns:

 A logical .TRUE. if the file pointer was successfully moved to
 the specified line, .FALSE. otherwise.

Arguments:

<nHandle> is the numeric file handle returned by DC_TXTOPEN().
Caution: This is NOT the dos file handle.

<nLineNumber> is the line in the text file to go to.

Examples:

 // This example will open the source code file and extract the
 // line of code that caused a runtime error.
 proc myerror

 cPrgName := dc_objfind( procname(1) )
 nLineNo := procline(1)
 nHandle := dc_txtopen( cPrgName )
 DC_TXTGOTO( nHandle, nLineNo )
 ? "This is the line of code that caused the error:"
 ? dc_txtline( nHandle )
 dc_txtclose( nHandle )

Files:

_DCTXT.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_txtopen()


dc_txtline()

Read the current line of a text file

DC_TXTLINE() will return the contents of the current line of text in a text file opened with DC_TXTOPEN().

Syntax:

DC_TxtLine ( <nHandle>, ;
             <cEol> ) -> cString

Returns:

 A string containing the contents of the current text line.

Arguments:

<nHandle> is the numeric file handle returned by DC_TXTOPEN().
Caution: This is NOT the dos file handle.

<cEol> is the character string sequence that determines the
end of a line.  The default is CHR(13)+CHR(10).

Examples:

 nHandle := dc_txtopen( 'dclip.sys' )
 do while !dc_txteof( nHandle )
   ? DC_TXTLINE( nHandle )
   dc_txtskip( nHandle, 1 )
 enddo
 dc_txtclose( nHandle )

Files:

_DCTXT.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_txtopen()


dc_txtlno()

Report the current line pointer of an open text file

DC_TXTLNO() is used to report the current line pointer in a text file that was opened with DC_TXTOPEN().

Syntax:

DC_TxtLNo ( <nHandle> ) -> nLine

Returns:

 The current line number pointer of the text file.

Arguments:

<nHandle> is the numeric file handle returned by DC_TXTOPEN().
Caution: This is NOT the dos file handle.

Examples:

 nHandle := dc_txtopen( 'dclip.sys' )
 ? DC_TXTLNO( nHandle )
 1
 dc_txtskip( nHandle, 2 )
 ? DC_TXTLNO( nHandle )
 3

Files:

_DCTXT.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_txtopen()


dc_txtopen()

Open a text file for use with Text file functions

DC_TXTOPEN() is used to open a text file for processing. The DC_TXT*() set of functions are used to access and read the information from text files much faster than can be accomplished via the standard Clipper low-level file functions.

Syntax:

DC_TxtOpen ( <cFileName> ) -> nHandle

Returns:

 A numeric file handle to be used by the other DC_TXT*()
 functions.

Arguments:

<cFileName> is the name of the text file to open.

Examples:

 nHandle := DC_TXTOPEN( 'dclip.sys' )
 do while !dc_txteof( nHandle )
   ? dc_txtline( nHandle )
   dc_txtskip( nHandle, 1 )
 enddo
 dc_txtclose( nHandle )

Files:

_DCTXT.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_txtclose()


dc_txtsize()

Return the size in bytes of an open text file

DC_TXTSIZE() returns the size of a currently opened text file that was opened with DC_TXTOPEN().

Syntax:

DC_TxtSize ( <nHandle> ) -> nBytes

Returns:

 The size of the text file in bytes.

Arguments:

<nHandle> is the numeric file handle returned by DC_TXTOPEN().
Caution: This is NOT the dos file handle.

Examples:

 nHandle := dc_txtopen( 'DCLIP.SYS' )
 ? DC_TXTSIZE( nHandle )
 672

Files:

_DCTXT.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_txtopen()


dc_txtskip()

Skip a specified number of lines in a text file

DC_TXTSKIP() is used to move the line pointer a specified number of lines in a text file opened with DC_TXTOPEN().

Syntax:

DC_TxtSkip ( <nHandle>, ;
             <nLines>, ;
             [<cEol>] ) -> nLinePointer

Arguments:

<nHandle> is the numeric file handle returned by DC_TXTOPEN().
Caution: This is NOT the dos file handle.

<nLines> is the number of text lines to skip.

<cEol> is the character string sequence that determines the
end of a line.  The default is CHR(13)+CHR(10).

Examples:

 nHandle := dc_txtopen( 'dclip.sys' )
 do while !dc_txteof( nHandle )
   ? dc_txtline( nHandle )
   DC_TXTSKIP( nHandle, 1 )
 enddo
 dc_txtclose( nHandle )

Files:

_DCTXT.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_txtopen()


dc_txtword()

Return value of a word in a String by specifying position

DC_TXTWORD() returns a specified word from the numerical position in the sentence.

Syntax:

DC_TxtWord ( <cString>, ;
             <nPosition>, ;
             [<cWhiteSpace>] ) -> cWord

Returns:

 The word corresponding to <nPosition>.  If <nPosition> is
 greater than the number of words in <cString> then a null
 will be returned.

Arguments:

<cString> is the string to search.

<nPosition> is the numerical position of the word.

<cWhiteSpace> is the character to be used as the "white
space" character. (The default is SPACE " ").

Examples:

 ? DC_TXTWORD( 'This is a test', 2)
 is

Files:

_DCTXT.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_token()


dc_unc2drive()

Converts a UNC path to a local mapped path

DC_UNC2Drive() converts a UNC to a mapped local drive letter.

Syntax:

DC_UNC2Drive( <cUNC> ) -> cDrive

Arguments:

<cUNC> is a UNC path.

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_drive2unc()


dc_updated()

Determine whether a GET changed during a READ

DC_UPDATED() determines whether characters were successfully entered into a GET from the keyboard during the most current READ. Each time READ executes, DC_UPDATED() is set to false (.F.). Then, any change to a GET entered from the keyboard sets DC_UPDATED() to true (.T.) after the user successfully exits the GET. If the user presses Esc before exiting the first GET edited, DC_UPDATED() remains false (.F.). Once DC_UPDATED() is set to true (.T.), it retains this value until the next READ is executed.<br><br> Within a SET KEY or VALID procedure, you can change the current GET variable using the KEYBOARD command or by assigning a new value with one of the many assignment operators. Changing the variable with KEYBOARD is the same as if the user had entered the change directly from the keyboard, and DC_UPDATED() is set accordingly. However, since DC_UPDATED() reflects only those changes made from the keyboard, an assignment to the GET variable does not affect DC_UPDATED(), therefore you should call call DC_UPDATED(.t.) to set the updated flag.

Syntax:

DC_Updated ( <lUpdated> ) -> lUpdated

Returns:

 .TRUE. if any GETS were updated during the read, .FALSE.
 otherwise.

Arguments:

<lUpdated> if .TRUE. will set the "updated" flag.  If no
parameter is passed, then only the current status will be
returned.

Notes:

DC_UPDATED() works with DC_READMODAL() in the same way that Clipper's UPDATED() works with READMODAL().

Examples:

 local cCustName, cPhoneNmbr
 store customer->cust_name to cCustName
 store customer->phone_nmbr to cPhoneNmbr
 @ 10,10 say 'Customer Name ' get cCustName
 @ 11,10 say 'Phone Number  ' get cPhoneNmbr
 dc_readmodal( GetList )
 IF DC_UPDATED() .and. dc_reclock()
   replace cust_name with cCustName
   replace phone_nmbr with cPhoneNmbr
   unlock
 ENDIF

Files:

_DCGETSY.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_readmodal()


dc_usearea()

Open a database file in a work area

DC_USEAREA() is a front-end to the Xbase++ dbusearea() function that can be used as a replacement for opening databases. This function tests the validity of a database and it's associated memo file (if it exists) before attempting to open it to prevent common errors. Working with different database drivers can make it difficult to determine the cause of an open error. This function is designed to test a database to make sure it is a proper type. Parameters passed to DC_USEAREA() are identical to dbusearea() so this function can be used as a replacement.<br><br> DC_USEAREA() tests the function DC_UseDBFProtect(). If this function returns a logical .TRUE. then, DC_USEAREA() first checks the header of the database to be opened to see if it has first been modified by DC_CloseArea(). DC_CloseArea() is used to modify the header of a .DBF style database before it is close to prevent other utility programs from being able to open the database. DC_USEAREA() will change the header first to insure that the database can be opened without errors.<br><br>

Syntax:

 DC_UseArea( [<lNew>], ;
             [<cDbe>], ;
             <cDatabase>, ;
             [<cAlias>], ;
             [<lShared>], ;
             [<lReadOnly>],
             [<lDisplayError>], ;
             [<lBreak>], ;
             [<lError>], ;
             [<lAutoOpen>], ;
             [<lUseAIndex>], ;
             [<cAltDbe>] ) -> nil

Returns:

 Nil.

Arguments:

<lNew> if .TRUE. will open the database in a new work area. If
.FALSE. (default), the current work area will be used.

<cDbe> is the DBE to use.  If no argument is passed, then the
<cAltDbe> will be used followed by the current DBE.

<cDatabase> is the name of the file to open.  If no drive and
directory is included then the file must exist in the SET
DEFAULT directory or SET PATH directory.

<lShared> if .TRUE. will open the database in SHARED mode, if
.FALSE. will open the database in EXCLUSIVE mode.  If no
argument is passed, then the system SET EXCLUSIVE value will be
used.

<lReadOnly> if .TRUE. will open the database for Read
operations only, if .FALSE. (default) will open the database
for Read/Write operations.

<cAlias> is the ALIAS to assign to the work area.  If no
argument is passed then the prefix of the database name will
be used as the alias.

<lDisplayError> if .TRUE. (default) will display an error window
if the file could not be opened.

<lBreak> if .TRUE. will BREAK after an error rather than RETURN.
The default is .FALSE.

@<lError> is a logical parameter, passed by reference.  If an
error occurs this variable will be set to .TRUE., otherwise it
will be set to .FALSE.

<lAutoOpen> is used to override the "auto-open" feature of the
some data drivers.  Passing a .FALSE. (default is .TRUE) will
force the data driver to NOT open any associated *.CDX index
file.

<lUseAIndex> if .TRUE. will open all indexes that start with
the same name as the database alias.

<cAltDbe> is an alternate DBE to use if the database cannot be
opened by the primary <cDbe> driver.

Examples:

 . DC_USEAREA ( .t., 'FOXCDX', 'EXPRESS',, .t., .f. )

Files:

_DCUSE.PRG, DCLIP2.DLL

See Also:

   dc_dbfile()
   USE
   dc_usedbfprotect()
   dc_closearea()


dc_usedbfprotect()

A Get/Set function for establishing data protection mode

DC_UseDBFProtect() is a Get/Set function used to set data protect mode ON or OFF. <br><br> If this function returns a logical .TRUE. then DC_CLOSEAREA() first modifies the header of the database before the database is closed to prevent other utility programs from being able to open the database. If a file header is modified by DC_CLOSEAREA(), then it can only be restored again by DC_USEAREA() by first calling DC_UseDBFProtect(.T.).<br><br><br><br>

Syntax:

 DC_UseDBFProtect( [<lProtect>] ) -> lStatus

Returns:

 A logical value.

Arguments:

 If <lProtect> is a logical .TRUE. then data protect mode is
 set ON.  If <lProtect> is a logical .FALSE. then data protect
 mode is set OFF.  If <lProtect> is not passed, then the
 function is used only to return the current setting.

Examples:

 . DC_UseDBFProtect(.t.)

 // open TEST.DBF
 . DC_UseArea( .t., 'DBFNTX', 'TEST' )

 // close TEST.DBF but first modify header to protect the data
 . DC_CloseArea()

Files:

_DCUSE.PRG, DCLIP2.DLL

See Also:

   dc_usearea()
   dc_closearea()


dc_useraccess()

Determine if Logged-On user has access to a lock

DC_USERACCESS() is used to established whether or not the logged-on user has possession of a key to a specified lock. If NO user has logged on with DC_USERLOGON() or the logged-on user is a programmer or the logged-on user has been assigned "no keys" then a logical .TRUE. will always be returned.

Syntax:

dc_useraccess ( <cLockCode>, ;
                [<cErrorMsg>] ) -> lStatus

Returns:

 A logical .TRUE. if the user possesses a key to the specified
 lock, .FALSE. otherwise.

Arguments:

<cLockCode> is a 5-character "Lock" code.

<cErrorMsg> is the message to display if the user does not
have posession of the key to the specified lock or a master
key.  If this parameter is not passed, then a default message
will be displayed.

Examples:

 #include 'dcuser.ch'
 DC_UserLogon( 'CURLY' )

 -- Example 1 --

 IF !DC_USERACCESS( '511', "Sorry.  You can't use this menu!" )
   RETURN
 ENDIF
 DC_MenuRun('MENU511')

Files:

_DCUSER.PRG

See Also:

   dc_usermaint()
   dc_userlogin()


dc_userfree()

Free the lock on the the User file to allow user access

DC_USERFREE() is used to remove the lock on the DCUSERS.DBF database that was previously used to lock out all users.<br><br>

Syntax:

dc_userfree ( ) -> Nil

Returns:

 Nil.

Arguments:

None.

Examples:

 ? DC_USERLOCK()
 .f.

Files:

_DCUSER.PRG

See Also:

   dc_usermaint()
   dc_userlock()


dc_userinfo()

Get or Set information about Logged-On User

DC_USERINFO() is used to set or get information about the logged-on user. This array is built when the user logs on with DC_UserLogOn() or DC_UserSet().

Syntax:

dc_userinfo ( [<nElement>], ;
              [<xValue>] ) -> aUserInfo | aUserInfo[nElement]

Returns:

 An array if <nElement> is not passed or a value dependent on
 the value of <nElement>.

 The array consists of 15 elements (See DCUSER.CH) for
 array definitions:

 Element   Type   Description
 -------  ----   -------------------------------------------
   [1]      C     USER_ID - User ID code
   [2]      C     USER_NAME - User Name
   [3]      C     USER_KEYS - User Keys (separated by commas)
   [4]      C     USER_MASTERPASS - Master Password
   [5]      L     USER_PROGRAMMER - "Programmer" flag
   [6]      C     USER_PASSWORD - Logged On User Password
   [7]      C     USER_MENU - User Start Menu Name
   [8]      C     USER_WPNAME - User Word Processor
   [9]      C     USER_WPPARAM - User Word Processor parameters
   [10]     C     USER_WPPATH - User Word Processor directory
   [11]     C     USER_GROUP - User Group
   [12]     L     USER_MAILFLAG - Mail Flag
   [13]     L     USER_PHONEFLAG - Phone message Flag
   [14]     L     USER_COLOR - Set Color ON Flag
   [15]     C     USER_PRINTER - User Printer Name
   [16]     C     USER_DEPT - User Department
   [17]     B     USER_WALL - Code Block for user wallpaper
   [18]     L     USER_MULTI - User Multiple Login enabled
   [19]     C     USER_JOB - User Job Name
   [20]     N     USER_NUM_UDF_1 - User Numeric UDF #1
   [21]     N     USER_NUM_UDF_2 - User Numeric UDF #2
   [22]     N     USER_NUM_UDF_3 - User Numeric UDF #3
   [23]     N     USER_CHAR_UDF_1 - User Numeric UDF #1
   [24]     N     USER_CHAR_UDF_2 - User Numeric UDF #2
   [25]     N     USER_CHAR_UDF_3 - User Numeric UDF #3
   [26]     N     USER_CHAR_UDF_4 - User Numeric UDF #4
   [27]     N     USER_CHAR_UDF_5 - User Numeric UDF #5
   [28]     N     USER_CHAR_UDF_6 - User Numeric UDF #6
   [29]     N     USER_LOGIC_UDF_1 - User Logical UDF #1
   [30]     N     USER_LOGIC_UDF_2 - User Logical UDF #2
   [31]     N     USER_DATE_UDF_1 - User Date UDF #1
   [32]     N     USER_DATE_UDF_2 - User Date UDF #2
   [33]     C     USER_SYSTEM - User System Name
   [34]     C     USER_APPTYPE - User Application Type
   [35]     C     USER_APPCODE - User Application Code
   [36]     C     USER_LOCATION - User Location
   [37]     C     USER_NUMBER - User Number

Arguments:

<nElement> is the array item to return.  If the <nElement>
argument is not passed then the entire array will be returned.

<xValue> is the value to store in aUserInfo[<nElement>].

Examples:

 #include 'dcuser.ch'
 DC_UserLogon( 'LARRY' )

 -- Example 1 --

 ? DC_USERINFO( USER_ID )

 LARRY

 -- Example 2 --

 /* -- Give user temporary access to all menus -- */
 DC_USERINFO( USER_KEYS, '' )

 -- Example 3 --

 ? DC_USERINFO()[ USER_KEYS ]
 1****,2****,31***,32000,32100,4****

Files:

_DCUSER.PRG

See Also:

   dc_usermaint()
   dc_userlogin()


dc_userlock()

Lock or attempt to lock all users out of the system

DC_USERLOCK() is used to lock or attempt to lock the DCUSERS.DBF database to prevent users from logging onto the system for maintenance purposes. This function will attempt to lock the file first. If other users are on the system, then the file cannot be locked and a list of logged on users will be displayed in the error message window.<br><br>

Syntax:

dc_userlock () -> lStatus

Returns:

 A logical .TRUE. if the file was locked successfully, .FALSE.
 otherwise.

Arguments:

<aErrorMsg> is an array of character strings to display as
the message in the event that the DCUSERS.DBF database cannot
be locked.  If this argument is not passed, then a default
message will be displayed.

Examples:

 ? DC_USERLOCK()
 .f.

Files:

_DCUSER.PRG

See Also:

   dc_usermaint()
   dc_userfree()


dc_userlogin()

Login to application to establish user rights

DC_USERLOGIN() is used to log a user onto the system in the event that it is necessary to establish rights to menus, files, or specified fields.<br><br> The eXPress++ menu system, data-entry (editing) system, browsing system, and file system provide for establishing locks on menu items, fields and/or files. If these systems are used without first calling DC_USERLOGIN(), then the user will be given full rights. If however, DC_USERLOGIN() is called first, then the user will be given access to only those items in which the user has the exact key or a master key for each specified lock.<br><br> If the user logs on with the MASTER PASSWORD, then he/she is automatically established as a "programmer" and is given full access. The MASTER PASSWORD is hard-coded by a definition in DCUSER.CH. To change the MASTER PASSWORD you must redefine it in DCUSER.CH and then recompile _DCUSER.DBF and include the new _DCUSER.OBJ in your link-script.<br><br> User PASSWORDS are stored in the DCUSER.DBF database in encrypted form. Passwords may be assigned or changed only with the DC_USERMAINT() function or the USER EDIT command.<br><br> User KEYS are stored in the DCUSER.DBF database and may be assigned or changed only with the DC_USERMAINT() function or the USER EDIT command. Locks are placed on menu items or fields by entering a 3-character "lock" sequence when using the menu-designer and/or data-entry designer. A database of standard locks and their definitions may be maintained by DC_LOCKMAINT(). When assigning a user a set of "keys" they may be specific keys or "master" keys. A Master key is assigned by using wild-cards. For example, the Master Key "5****" will allow access to any lock starting with the number "5", whereas the Master Key "67***" will allow access to any lock with the number "67". Keys are stored in the USR_KEYS field and are separated by commas.<br><br> Example:<br><br> "1****,2****,3****,41***,42***,52231,6****"<br><br>

Syntax:

dc_userlogin ( [<cUserID>], ;
               [<cPassword>], ;
               [<nStartRow>], ;
               [<oParent>] ) -> lStatus

Returns:

 A logical .TRUE. if the user logs on successfully, .FALSE.
 otherwise.

Arguments:

<cUserID> is the User ID of the logging on user.  If this
parameter IS NOT passed and the <cPassword> parameter IS
passed, then the DCUSERS.DBF will be searched only for a
match to the <cPassword>.  If <cUserID> is passed and
<cPassword> is not passed, then the user will be prompted to
enter a password.  If neither <cUserID> or <cPassword> is
passed, then the user will be prompted for both a User ID
and a password.

<nStartRow> is the starting display row of the screen.  This is
ignored if the DC_Gui() flag is on because the dialog is centered
withing its parent.

<oParent> is the parent window that will receive the user dialog
window.  If this argument is a nil the parent will be the
AppDesktop().

Examples:

 #include 'dcuser.ch'

 DC_USERLOGIN( 'LARRY' )

Files:

_DCUSER.PRG

See Also:

   dc_usermaint()


dc_usermaint()

Maintain the DCUSERS.DBF User Database

DC_USERMAINT() is used to maintain the DCUSER.DBF database for establishing User ID's, Names, Passwords, Access Keys, etc. <br><br>

Syntax:

 DC_UserMaint ( [<cUserID>] ) -> lStatus

Returns:

 A logical .TRUE. if the user database was opened and accessed,
 .FALSE. otherwise.

Arguments:

If the <cUserID> argument is passed, then the record that
contains the USR_ID matching <cUserID> will be edited,
otherwise all records will be available for browsing and
editing.

Examples:

 #include 'dcuser.ch'

 -- Example 1 --

 DC_USERMAINT( 'LARRY' )

 -- Example 2 --

 DC_USERMAINT()

Files:

_DCUSER.PRG

See Also:

   dc_userlogin()


dc_userset()

stablish the Logged-On user from the User Database

DC_USERSET() is used to load the logged-on user array from a specifed record in the DCUSERS.DBF database.<br><br>

Syntax:

dc_userset ( <cUserID> ) -> lStatus

Returns:

  A logical .TRUE. if the User ID was found in the database,
 .FALSE. otherwise.

Arguments:

<cUserID> is a valid user id that matches the value in the
USR_ID field of the DCUSER.DBF database.

Examples:

 DC_USERSET( 'MOE' )

Files:

_DCUSER.PRG

See Also:

   dc_usermaint()
   dc_userinfo()


dc_util()

A menu of database utilities

DC_UTIL() provides a set of general-purpose database utilities to perform menu-driven, complex database operations on the currently selected work area. Menu Selections --------------------- Create Database Display Structure Modify Structure Copy Structure Append Records Copy Records Import a Data File Replace Data Copy Fields Delete Records Recall Records Sort Database Join with Database Count Records Sum Data Fields Average Data Fields Disk Directory Insert Blank Record(s) Pack DataBase Zap Database Import/eXport Memos Purge Duplicate Records<br><br>

Syntax:

 DC_Util() -> nil

Returns:

 Nil.

Examples:

 . USE COLLECT
 . DC_Util()

Files:

_DCUTIL.PRG, DCLIP2.DLL

See Also:

   UTIL


dc_validateblock()

Validate a code block string

DC_ValidateBlock() is used to validate a string that must later be macro-compiled into a code block. It attempts to compile the string and traps and possible errors.

Syntax:

DC_ValidateBlock( <cBlock>, ;
                  [<cValType>], ;
                  [@<bBlock>] ) -> lValid

Returns:

A logical .TRUE. if a valid expression or codeblock was passed.

Arguments:

<cBlock> is the string to be validated.  If the string does
not start with a valid code block identifier: {| then this will
be added to the string to blockify it before testing it.

<cValType> is a string containing the valid types of values
that may be returned by the code block when it is evaluated.
Default is '(C)har), (D)ate, (N)umeric, (L)ogical, (U)ndefined'.
This string is used to validate the output and also to display
a user message if the code block returns an incorrect value.

@<bBlock> is the name of a variable (passed by reference) to
store the resultant compiled code block.

Examples:

@ 1,1 DCSAY 'Enter Expression or Code Block' ;
  GET cBlock ;
  VALID {||DC_ValidateBlock(cBlock)}

Files:

_DCEVAL.PRG, DCLIPX.DLL


dc_valtype()

Validate input parameters and set default values

DC_VALTYPE() is a handy way of validating paramters that are passed to functions and filling them with default values if the parameter is not passed or if the wrong type of parameter is passed.

Syntax:

DC_ValType( @<cMemVar>, ;
            <xDefaultVal> [,...] ) -> nil

Returns:

 NIL

Arguments:

<cMemVar> is the memory variable to validate.

<xDefaultVal> is the value to initialize <cMemVar> if the
<cMemVar> is not the same type as <xDefaultVal>.

Notes:

DC_VALTYPE() supports type-checking on up to 15 variables. If you need to validate more than 15 variables, then call DC_VALTYPE() a second time with the remaining variables.

Examples:

 function window ( nStRow, nStCol, nEnRow, nEnCol, cTitle )

 DC_VALTYPE( @nStRow, 0, @nStCol, 0, @nEnRow, MaxRow(), ;
     @nEnCol, MaxCol(), @cTitle, "" )

 return dc_expl( nStRow, nStCol, nEnRow, nEnCol, cTitle )

Files:

_DCVAL.PRG/.OBJ, DCLIPX.LIB

See Also:


dc_var2hexstring()

Convert a binary string to a Hex String

DC_Var2HexString() is used to convert binary strings to hex equivalent for storing in .TXT files or in memo fields that do not accept binary data.<br><br>

Syntax:

DC_Var2HexString( <cBinaryString> ) -> cHexString

Returns:

A Character String.

Arguments:

<cBinaryString> is a binary string create by Var2Bin().

Examples:

// Save Directory to a memo field
aData := Directory()
cData := DC_Var2HexString(Var2Bin(aData))
REPLACE CUSTOMER->directory WITH cData

// Restore Directory from a memo field
cData := DC_HexString2Var(CUSTOMER->directory)
aData := Bin2Var(cData)

Files:

_DCASAVE.PRG, DCLIPX.DLL

See Also:


dc_var2sql()

Convert Xbase++ value to SQL value

DC_Var2SQL() is used to convert any Xbase++ value of type C, L, M, N, or D to a character string which can be inserted into a SQL statement.<br><br>

Syntax:

DC_Var2SQL( <xValue> ) -> <cSQLvalue>

Returns:

A character string.

Arguments:

<xValue> is any Xbase++ value of type C, M, L, N or D.

Examples:

cSQL := 'SELECT * FROM invoices WHERE duedate >= ' + ;
        DC_Var2SQL( Date() )

Files:

_DCADS.PRG, DCLIPX.DLL

See Also:

   dc_adsstatement()
   dc_applysqlparams()


dc_varfromlistbox()

Store List box choices into memory variable array

DC_VARFROMLISTBOX() is used to transfer a set of marked items in a DCCOMBOBOX, DCLISTBOX or DCPICKLIST object into the memory variable previously assigned to the object.

Syntax:

 DC_VarFromListBox( <oObject> ) -> nil

Returns:

 Nil.

Arguments:

<oObject> is a ListBox object created with the @ DCLISTBOX
command, a ComboBox object createdwith the @ DCCOMBOBOX command,
or a PickList object created with the @ DCPICKLIST command.

Examples:

PROCEDURE XTest()

LOCAL GetList := {}, aFields:={}, aOutput:={}
LOCAL oListBox

AADD(aFields, 'Alice')
AADD(aFields, 'Bob')
AADD(aFields, 'Carol')
AADD(aFields, 'Dick')
AADD(aFields, 'Harry')
AADD(aFields, 'Ted')
AADD(aFields, 'Tom')

@ 0,0 DCLISTBOX aOutput LIST aFields ;
   FONT "10.Courier" ;
   SIZE 15,10 ;
   OBJECT oListBox ;
   SELECT {2,4,5,6,7}

@ 0, 17 DCPUSHBUTTON ;
   CAPTION '~Mark All' ;
   SIZE 10, 1.1 ;
   FONT '8.MS Sans Serif' ;
   ACTION {|| AEVAL(aFields, {|x,i| oListBox:setData(i, .T.)}), ;
              DC_VarFromListBox(oListBox)} ;
   RELATIVE oListBox

@ 1.5, 17 DCPUSHBUTTON ;
   CAPTION 'C~lear All' ;
   SIZE 10, 1.1 ;
   FONT '8.MS Sans Serif' ;
   ACTION {|| AEVAL(aFields, {|x,i| oListBox:setData(i, .F.)}), ;
              DC_VarFromListBox(oListBox)} ;
   RELATIVE oListBox

DCREAD GUI ;
  TITLE 'List Box Demo' ;
  FIT ;
  ADDBUTTONS

DC_MsgBox(aOutput)

RETURN

Files:

_DCGETBX.PRG, DCLIPX.DLL

See Also:

   @ DCLISTBOX
   @ DCCOMBOBOX
   @ DCPICKLIST
   dc_vartolistbox()


dc_vartolistbox()

Store memory variable array into ListBox

DC_VARTOLISTBOX() is used to transfer an array of character strings into the ListBox object of a DCCOMBOBOX, DCLISTBOX or DCPICKLIST object.

Syntax:

 DC_VarToListBox( <oObject>, ;
                  [<aItems>], ;
                  [<aMarked>] ) -> nil

Returns:

 Nil.

Arguments:

<oObject> is a ListBox object created with the @ DCLISTBOX
command, a ComboBox object createdwith the @ DCCOMBOBOX command,
or a PickList object created with the @ DCPICKLIST command.

<aItems> is an optional array of character strings to store into
the ListBox object.  If no array is passed, then the array
anchored to the @ DCLISTBOX, @ DCCOMBOBOX, or @ DCPICKLIST
command will be stored to the ListBox object.

<aMarked> is an optional array of numeric values which is used
to pre-select a set of items.

Examples:

PROCEDURE XTest()

#include "dcdialog.ch"
#include "dcpick.ch"

LOCAL GetList := {}
LOCAL GetOptions

LOCAL aMen := {}
LOCAL aWomen := {}
LOCAL aListField := {}
LOCAL aPickField := {}
LOCAL oPickList
LOCAL cOption

AADD(aMen, 'Bob')
AADD(aMen, 'Dick')
AADD(aMen, 'Harry')
AADD(aMen, 'Ted')
AADD(aMen, 'Tom')

AADD(aWomen, 'Alice')
AADD(aWomen, 'Carol')

AADD(aListField, 'One')
AADD(aListField, 'Two')
AADD(aListField, 'Three')

@1,3 DCRADIO cOption PROMPT 'Women' VALUE 'W' ;
     ACTION {|| aListField := aWomen, DC_VarToListBox(oPickList) }

@2,3 DCRADIO cOption PROMPT 'Men' VALUE 'M' ;
     ACTION {|| aListField := aMen, DC_VarToListBox(oPickList) }

@4,3 DCPICKLIST aPickField LIST aListField ;
   CAPTION "Available People", "Selected People" ;
   SIZE 35,12 ;
   OBJECT oPickList

DCREAD GUI ;
   TITLE "Pick a Person" ;
   ADDBUTTONS ;
   FIT

DC_MsgBox(aPickField)

RETURN

Files:

_DCGETBX.PRG, DCLIPX.DLL

See Also:

   @ DCLISTBOX
   @ DCCOMBOBOX
   @ DCPICKLIST
   dc_varfromlistbox()


dc_versionexpress()

Returns the current eXPress++ version

DC_VERSIONEXPRESS() returns the current version of eXPress++.

Syntax:

DC_VersionExpress( <nMode> ) -> cVersion

Returns:

A character string.

Arguments:

<nMode> is a numeric value designating the version information
being polled.

<nMode>     Returns
-------     -------------------------------------------------
   0        Full version description
            Example: eXPress++ (c) Version 1.3

   1        Major Revision level
            Example: 1

   2        Minor Revision level
            Example: 3

   3        Build Number
            Example: 104

Files:

_DCFUNCT.PRG, DCLIPX.LIB


dc_virtcapt()

Capture the current record to a Virtual record array

DC_VIRTCAPTURE() is used to capture the data in all fields of the current database to a VIRTUAL record array to be used with other DC_VIRT*() functions.

Syntax:

dc_virtcapture ( [<lFieldNames>] ) -> aVirtualRecord

Returns:

 If <lFieldNames> is .TRUE., returns single-dimensional array with
 a number of elements equal to the number of fields in the
 current database.

 If <lFieldNames> is .FALSE., returns a multi-dimensional array
 of two elements:  The first is an array of field names, the
 second is an array of data.

Arguments:

If <lFieldNames> is a logical .TRUE., then the field name data
will be saved in the array returned.  DC_VIRTREPLACE() will
automatically know if the field data information is in the array
and will not cause an error if the structure of the target
database is not the same as the structure of the primary database.

IF <lFieldNames> is .FALSE., then the target database must
exactly match the structure of the primary database.

Examples:

 . USE COLLECT
 . GO 5
 . aVirtual := DC_VirtCapt()
 . DC_ArrayView( aVirtual )

Files:

_dcvirt.prg, DCLIP2.DLL

See Also:

   dc_virtrepl()


dc_virtrepl()

Replace the current record contents with Virtual record arra

DC_VIRTREPLACE() will replace the contents of the current record with the data in a virtual record array. This function will automatically handle the record locking, so it is not necessary to lock the record.<br><br>

Syntax:

dc_virtreplace ( <aVirtualRecord> ) -> lStatus

Returns:

 A logical .TRUE. if the data replacement is successful, .FALSE.
 otherwise.

Arguments:

<aVirtualRecord> is a virtual record array saved by DC_VIRTSAVE().

Examples:

 . USE COLLECT
 . GO 5
 . aVirtual := DC_VirtCapt()
 . GO 6
 . DC_VirtRepl( aVirtual )

Files:

_dcvirt.prg, DCLIP2.DLL

See Also:

   dc_virtcapt()


dc_virtrest()

Restore the virtual record contents to an array

DC_VIRTRESTORE() will create a virtual record array from the contents of a virtual record (.DCV) file which was created with the DC_VIRTSAVE() function.<br><br><br><br>

Syntax:

dc_virtrestore ( ) -> aVirtualRecord

Returns:

 An array with the contents of the .DCV file.

Arguments:

 None.

Examples:

 // this routine will append 5 records to the current database
 // that will be filled in with data from the virtual record.
 aVirtual := DC_VIRTRESTORE()
 if valtype(aVirtual) = 'A'
   for i := 1 to 5
     dc_addrec()
     dc_virtreplace( aVirtual )
   next
 endif

Files:

_dcvirt.prg, DCLIP2.DLL

See Also:

   dc_virtcapt()
   dc_virtrepl()
   dc_virtsave()


dc_virtsave()

Save the current record to the virtual record file

DC_VIRTSAVE() will save the contents of a virtual record array or the current database record to a virtual record (.DCV) file. The file will have the same name as the current database file name except it will have the .DCV extension, and will be located in the same directory as the database file.<br><br> A virtual record can be used as a "data template" for multiple purposes:<br><br> 1. To fill in default data when appending a new record.<br><br> 2. To be used to cut and paste data from one record to another.<br><br><br><br><br><br>

Syntax:

dc_virtsave ( <aVirtualRecord> ) -> lStatus

Returns:

 A logical .TRUE. if the save was successful, .FALSE. otherwise.

Arguments:

<aVirtualRecord> is a virtual record array saved by
DC_VIRTSAVE(). If no argument is passed, then the contents of
the current record in the current work area will be used as the
virtual record.

Examples:

 . USE COLLECT
 . GO 5
 . DC_VirtSave()  // Create COLLECT.DCV

Files:

_dcvirt.prg, DCLIP2.DLL

See Also:

   dc_virtcapt()
   dc_virtrepl()
   dc_virtrest()


dc_wait()

3 Dual-Mode replacement for the WAIT command

DC_WAIT() is a Dual-mode replacement for the WAIT command. When the GUI flag is ON, DC_WAIT() functions similiar to WAIT except that it is displayed in GUI mode. When the GUI flag is OFF, DC_WAIT() functions identical to WAIT except it is also activated by a mouse.

Syntax:

DC_Wait ( [<cMessage>] ) -> nil

Arguments:

<cMessage> is the message to display.

Examples:

 nHandle := dc_txtopen( '\clipper5\include\std.ch' )
 nLine := 0
 do while !dc_feof( nHandle ) .and. lastkey()#27
   ? dc_txtline( nHandle )
   dc_txtskip( nHandle, 1 )
   nLine++
   if nLine > maxrow()-3
     DC_WAIT( "Press any key to continue, Escape to Abort")
     nLine := 0
   endif
 enddo
 dc_txtclose( nHandle )

Files:

_DCWAIT.PRG/.OBJ, DCLIPX.LIB


dc_waiton()

A Dual-Mode dialog for "Work in Progress"

DC_WAITON() is a Dual-mode dialog function that displays a "Waiting" message to the user. In GUI mode, it will optionally display a "Work-in-Progress" progress bar to notify the user that the program is running and is busy.<br><br> The function will operate in TEXT mode by invoking DC_GUI(.F.) to set the system mode or in GUI mode by invoking DC_GUI(.T.).

Syntax:

DC_WaitOn ( [<abcMessage>], ;
            [<lSound>], ;
            [<cColor1>], ;
            [<cColor2>], ;
            [<nTop>], ;
            [<nLeft>], ;
            [<lWorking>], ;
            [<oParent>] ;
            [<oOwner>], ;
            [<lModal>] ) -> aDialog

Returns:

 An array of information which is used by DC_IMPL() to restore
 the screen (in TEXT mode) or to destroy the dialog (in GUI mode).
.

Arguments:

<abcMessage> is the message to place in the window.  If this
is passed as an array, then each element must be a character
string representing each line of text in the window.  If it
is passed as a code block then the code block must return
either a character string or an array of character strings. If
no argument is passed then the following default message will
be displayed: "Please wait..."

<lSound> if .TRUE. will create a warning tone.  .FALSE. is
default.  This argument is ignored in GUI mode.

<cColor1> is the color of the window frame.  If no argument
is passed then the system color for "exploding box frame" will
be used.  This argument is ignored in GUI mode.

<cColor2> is the color of the window contents.  If no
argument is passed then the system color for "exploding box
contents" will be used.  This argument is ignored in GUI mode.

<nTop> is the top display row of the message box.  If no
argument is passed, then the box will be vertically positioned
in the center of the screen.  This argument is ignored in GUI
mode.

<nLeft> is the left display column of the message box.  If no
argument is passed, then the box will be horizontally
positioned in the center of the screen.  This argument is ignored
in GUI mode.

<lWorking> if .TRUE. (default) will display a "Work in Progress"
progress bar (running in another thread) which is constantly
moving until the dialog is destroyed.  This argument is ignored
in TEXT mode.

<oParent> is the parent object.  If this parameter is NIL or is
passed then the parent will be the AppDeskTop().

<oOwner> is the owner.  If this parameter is NIL or is not passed
then the owner will be <oParent>.

<lModal> if .FALSE. will make the window modeless.  The default is
.TRUE.

Examples:

 FUNCTION Xtest()

 LOCAL cDialog

 USE ..\XDOC\EXPRESS VIA FOXCDX ALIAS XDOC EXCLUSIVE

 cDialog := DC_WaitOn('Please wait while copying file')
 COPY TO JUNK
 Ferase('JUNK.*')
 DC_Impl(cDialog)

 RETURN nil

Files:

_DCEXPL.PRG/.OBJ, DCLIPX.DLL


dc_webserverdomainname()

Set the Web Server domain name for web applications

DC_WebServerDomainName() is used to set the domain name of the server that is serving up the application code.

Syntax:

DC_WebServerDomainName( [<cDomain>] ) -> cOldDomain

Returns:

A character string.

Arguments:

<cDomain> is the domain name of the server (as used in URLs).

Examples:

DC_WebServerDomainName('Donnay-Software.Com')

Files:

_DCHTML.PRG

See Also:

   dc_readhtml()


dc_wildcardmatch()

Test if a string matches a wildcard

DC_WildCardMatch() is used to test if a string matches a wildcard string that contains asterisk (*) characters.

Syntax:

DC_WildCardMatch( <cString>, ;
                  <cWildCard> ) -> lStatus

Arguments:

<cString> is a string of characters.

<cWildCard> is a string of characters containing asterisks.

Examples:

? DC_WildCardMatch( 'testing', 'Test*' )
.F.

? DC_WildCardMatch( 'testing', 'test*' )
.T.

? DC_WildCardMatch( 'App.Text.1', 'App.*.*' )
.T.

Files:

_DCHTML.PRG, DCLIPX.DLL

See Also:

   dc_htmlvars()


dc_winalert()

Popup a GUI alert box

DC_WinAlert() is a simple front-end to the Xbase++ ConfirmBox() function that requires only a single parameter to popup a GUI confirmation box with a default as an alert box.<br><br>

Syntax:

DC_WinAlert( <cMessage>, ;
             [<cTitle>], ;
             [<nButtons>], ;
             [<nStyle>], ;
             [<nDefButton>], ;
             [<oOwner>] ) -> nResult

Returns:

Constants for the return value

  Constant          Description

  XBPMB_RET_OK      "Ok" pushbutton pressed
  XBPMB_RET_CANCEL  "Cancel" pushbutton pressed
  XBPMB_RET_ABORT   "Cancel" pushbutton pressed
  XBPMB_RET_RETRY   "Retry" pushbutton pressed
  XBPMB_RET_IGNORE  "Ignore" pushbutton pressed
  XBPMB_RET_YES     "Yes" pushbutton pressed
  XBPMB_RET_NO      "No" pushbutton pressed
  XBPMB_RET_ENTER   "Enter" pushbutton pressed

  XBPMB_RET_ERROR   Confirm box could not be displayed

Arguments:

<cMessage> is a character string containing the text to display
in the confirmation box. Carriage return (Chr(13)) and line feed
(Chr(10)) act as new line characters. Carriage return causes the
text to be displayed on the next line and line feed on the line
after that. In other words, Chr(10) first inserts a blank line.

<cTitle> is a character string that is displayed in the title
bar of the confirmation box. The default value is AppName().

<nButtons> is a numeric constants for determining pushbuttons
under Windows

  Constant                Text for pushbuttons

  XBPMB_OK                Ok
  XBPMB_OKCANCEL     *)   Ok and Cancel
  XBPMB_ABORTRETRYIGNORE  Cancel, Retry and Ignore
  XBPMB_YESNO             Yes and No
  XBPMB_YESNOCANCEL       Yes, No and Cancel

 *) Default value

<nStyle> is used to specify an optional system icon that can be
selected for display to the left of the text in the confirmation
box. The following constants can be used:

Constants for defining icons

  Constant             Icon

  XBPMB_NOICON     *)  No icon
  XBPMB_QUESTION       Question mark
  XBPMB_WARNING        Warning
  XBPMB_INFORMATION    Information
  XBPMB_CRITICAL       Critical situation

 *) default value

In addition, the following constants for <nStyle> can be used
to control the modality of the confirmation box. If a constant
for an icon is used, the constants must be added to those in
the following table:

Additional constants for <nStyle>

  Constant        Description

  XBPMB_APPMODAL  Confirm box is modal in relation to the
                  Xbase++ application
  XBPMB_SYSMODAL  Confirm box is modal system wide
  XBPMB_MOVEABLE  Confirm box can be moved

<nDefButton> optionally specifies the pushbutton that is to have
input focus immediately after the confirmation box is displayed.
The following constants are valid:

Constants for the definition of focus

  Constant              Pushbutton

  XBPMB_DEFBUTTON1  *)  First pushbutton has input focus
  XBPMB_DEFBUTTON2      Second pushbutton has input focus
  XBPMB_DEFBUTTON3      Third pushbutton has input focus

 *) Default value

<oOwner> specifies the owner of the confirmation box. By default
<oOwner> is the return value of SetAppWindow().

Examples:

. DC_WinAlert('The disk is full')

Files:

_DCMSG.PRG

See Also:

   dc_msgbox()


dc_windowlist()

Pop up a list of open windows

DC_WindowList() will popup a list of open windows and allow the user to bring that window to the front.<br><br>This function is handy when there are so many open windows that some get hidden behind others. This only works for child windows of the application.

Syntax:

DC_WindowList( <oParent>, ;
               <oButton> ) -> nil

Arguments:

<oParent> is a pointer to the parent object that has a childlist
of windows.

<oButton> is a pointer to the pushbutton object that is used
to invoke the function.

Examples:

DCSTATUSBAR oStatBot TYPE XBPSTATIC_TYPE_RECESSEDBOX HEIGHT 20 ALIGN DCGUI_ALIGN_BOTTOM

@ 0,0 DCSAY '' PARENT oStatBot SIZE 300,20 PIXEL ;
      OBJECT oMessage COLOR GRA_CLR_BLUE FONT '10.Lucida Console' SAYLEFT

@ 0,0 DCSTATIC TYPE XBPSTATIC_TYPE_RAISEDBOX PARENT oStatBot SIZE 5,20 PIXEL

@ 0,0 DCPUSHBUTTON CAPTION 'Windows' SIZE 80,20 PIXEL ;
      ACTION {|a,b,o|DC_WindowList(oDlg:drawingArea,o)} PARENT oStatBot

Files:

_DCFUNCT.PRG, DCLIPX.DLL


dc_winmenudestroymode()

A Get-Set function for setting AUTOWINMENU destroy mode

DC_WinMenuDestroyMode() is used to establish the method in which the menu item under the "Windows" menubar item is removed when the window is closed. MDI applications are typically written either single-threaded or multi-threaded. When an MDI application uses the AUTOWINMENU feature of DCGETOPTIONS a menu item is added to the "Windows" menu when the dialog is created and it is removed when the dialog is destroyed. If the dialog is automatically destroyed when exiting DC_ReadGui(), i.e. windows are in separate threads, then the destroying of the menu item is also automatic. If the dialog is destroyed by the xbeP_Close event, i.e. windows are all in the same thread, then the menu item must also be destroyed by the same event.

Syntax:

DC_WinMenuDestroyMode( [<nMode>] ) -> nOldMode

Returns:

A numeric value

Arguments:

<nMode> is a numeric value defined in DCDIALOG.CH:

DCGUI_WINMENU_DESTROYMODE_EXIT (default) - destroy menu item
when exiting DC_ReadGui().

DCGUI_WINMENU_DESTROYMODE_CLOSE - destroy menu item when
xbeP_Close event is received.

Files:

_DCCLASS.PRG, DCLIPX.DLL

See Also:


dc_word2num()

Convert a 2-byte word to an integer number

DC_WORD2NUM() is used to convert a 2-byte word to an integer.<br><br>

Syntax:

 DC_Word2Num ( <cByteString> ) -> nNumber

Returns:

 An integer number.

Arguments:

<cByteString> is a 2-byte character string.

Examples:

 The following example shows how to use DC_NUM2WORD() and
 DC_WORD2NUM() to save numeric values to a file and restore
 them.

 FUNCTION savenumbers ( aNumbers )

 // aNumbers := { 10, 45, 134, 678, 3, 200 }
 nHandle := fcreate( 'numbers.bin' )
 for i := 1 to len(aNumbers)
   fwrite( nHandle, DC_NUM2WORD( aNumbers[i] )
 next
 fclose( nHandle )
 return

 FUNCTION restnumbers

 local nHandle := fopen( 'numbers.bin' )
 local aNumbers := {}
 aadd( aNumbers, DC_WORD2NUM( freadstr( nHandle, 2 ) ) )
 fclose( nHandle )
 return aNumbers

Files:

_DCNUM.PRG, DCLIP2.DLL

See Also:

   dc_num2word()


dc_workarea2csv()

Exports the data in the current work area to a CSV file

DC_WorkArea2Csv() will create a comma-delimted CSV file from the contents of the current work area. All scopes and filters will be respected.

Syntax:

DC_WorkArea2CSV( <cFileName>, ;
                 [<aFields>], ;
                 [<cDateFormat>] ;
                 [<aFieldEvals>] ) -> lSuccess

Returns:

A logical value.

Arguments:

<cFileName> is the name of the CSV file to create.

<aFields> is a single-dimension array of field names to export.
The default is all fields.

<cDateFormat> is the format of date fields to export. The default is
mm/dd/yyyy.

<aFieldEvals> is a 2-dimensional array of fieldnames and codeblcoks
to evaluate to return a value for a specified field.  This is used
for custom formatting of data.  Each code block must return a
character string.

Ex. {{FIELDNAME,CodeBlock},....}

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_csv2workarea()


dc_workarea2excel()

Create an Excel Spreadsheet from data in a Work Area

DC_WorkArea2Excel() is use to create an Excel spreadsheet (*.XLS) file from the data in a workarea.

Syntax:

DC_WorkArea2Excel( [<cExcelFile>], ;
                   [<nOrientation>], ;
                   [<lDisplayAlerts>], ;
                   [<lVisible>], ;
                   [<aFields>], ;
                   [<lAutoFit>], ;
                   [<cDateFormat>], ;
                   [<aFieldEvals>], ;
                   [<cPassword>], ;
                   [<lFreezeRow1>, ;
                   [<lCsvFallBack>], ;
                   [<aColumnNames>] ) -> lStatus

Returns:

A logical .true. if the spreadsheet could be created, .false.
otherwise.

Arguments:

<cExcelFile> is the name of the excel file (*.XLS) to be created.
If this parameter is not passed, the file will be created in the
same directory as the application .exe and will be named WORKSHEET.XLS.

<nOrientation> is the orientation of the spreadsheet.  A value of
1 creates a "portrait" orientation.  A value of 2 creates a
"landscape" orientation (default).

<lDisplayAlerts> will prompt the user if the file being created
will be overwritten.  The default is .f.

<lVisible> will display the spreadsheet while the cells are being
filled.  Default is .f.

<aFields> is a single-dimensional array of field names to include
in the spreadsheet.  The columns will be created in the same
order as the fields in the array.  If <aFields> is not passed
or is empty, then all fields in the database will be exported.

<lAutoFit> will optimize the columns of the spreadsheet to fit
the data to it's optimum width, otherwise the columns will be
the width of the database field.  Default is .t.

<cDateFormat> is used to format date fields based on excel specs.

This can be:
'US' = 03/16/2011
'USSHORT' = 3/16/2011
'EURO' = 16/03/2011
'EUROSHORT' = 16/3/2011
an actual date mask ie.: 'dd-mmm-yyyy' = 16-Mar-2011

<aFieldEvals> is an array of code blocks that is used to custom-format
the data.

Example:

aFieldEvals := { {'INDEX_NO',{|x|DispIndxNo(x)}}, ;
                 {'CUST_NO',{|x|LastFromCustNo(x)}} }

Replaces all data from 'INDEX_NO' fields with DispIndxNo(field->Index_no)
Replaces all data from 'CUST_NO' fields with Customer last name

<cPassword> is a password to apply to the file to allow viewing by
Excel.

<lFreezeRow1> if .TRUE. causes the first row of the Excel sheet to be
bold font and locked from scrolling.  The default is .FALSE.

<lCsvFallBack> if .TRUE. will cause the output to be a .CSV file in
the event that the Excel ActiveX control is not installed.

<aColumnNames> is a 1-dimensional array with the names of the
columns.  The default is the field name.

Examples:

USE CUSTOMER

aFields := { 'CUST_NMBR','CUST_NAME','BALANCE' }

DC_WorkArea2Excel('CUSTOMER.XLS',,,,aFields)

DC_SpawnUrl('CUSTOMER.XLS')

Files:

_DCFUNCT.PRG, DCLIPX.DLL, DCLIPX.LIB

See Also:

   dc_excel2workarea()
   dc_array2excel()


dc_workarea2xml()

Export a workarea to an XML file

DC_WorkArea2Xml() will export a the records in a workarea to a file that conforms to XML format.<br><br>The XML file will contain both structure and data.<br><br>Only records that meet the current scope and/or filter will be exported.<br><br>

Syntax:

DC_WorkArea2Xml( [<cXmlFile>], ;
                 [<aStructure>] ) -> lStatus

Returns:

A logical .TRUE. if the file could be created, .FALSE. otherwise.

Arguments:

<cXmlFile> is the name of the XML file to create.
If this argument is not passed, then the file will be named
Alias() + '.XML'.

<aStructure> is a structure array that conforms to the array
returned by the function dbStruct().  If this array is not passed,
then all fields will be exported.  If the array is passed, then
only the fields in the array will be exported.

Examples:

See eXpress++ samples: .\SAMPLES\XML\WORKAREA.PRG.

Files:

dcxml.dll, _dcxml.prg

See Also:

   dc_xmlnode()


dc_working()

Display a "Working in Progress" bar

DC_WORKING() is used to display "Working" progress bullets for displaying the progress of any operation. This is a dual-mode function. If DC_GUI(.t.) is called before calling DC_WORKING(), then the working dialog will be GUI. If DC_GUI(.f.) is called before calling DC_WORKING(), then the working dialog will be text-based.

Syntax:

dc_working ( <nMode>, ;
             <cTitle>,;
             <nStRow>,;
             <nStCol>,;
             <nEnCol>,;
             <lBox>,;
             <cColors>,;
             <nUpdate>,;
             <lCenter>,;
             <aPointer>,;
             @<lCancel> ) -> nil

Returns:

 Nil

Arguments:

<nMode> is a number 0,1, or 2 depending on the function
desired:

 0 - Initialize Static values and display bullet
 1 - Paint new bullet if timer exceeded
 2 - Terminate and restore screen

<cTitle> is the message to display in the box.  If no
parameter is passed then "Working" will be displayed.

<nStRow> is the start display row.  This parameter is used
only if <nMode> is 0.

<nStCol> is the start display column.  This parameter is used
only if <nMode> is 0.

<nEnCol> is the end display column.  This parameter is used
only if <nMode> is 0.

<lBox> if .TRUE. (default) will paint a box around the progress
bar starting at the passed coordinates, otherwise the progress
bar only will be painted starting at the passed coordinates.

<cColors> is a character string containing 2 color specfications
separated by a comma.  The first color is the color of the box,
the second is the color of the progress bullets.  If no parameter
is passed, then the current system color will be used for both
colors.

<nUpdate> is the amount of time (in seconds) to wait before
painting the next bullet.  Default value is .3 seconds.

<lCenter> if .TRUE. will center the dialog will center the dialog
within the application window.  This parameter is used only in GUI
mode.

<aPointer> is an optional array of 3 elements defining the mouse
pointer to use for the dialog and the application window.  The
mouse pointer will be changed to the passed value until DC_Working()
is called again with an <nMode> value of 2.  <aPointer> is used
only in GUI mode.

ELEMENT     DESCRIPTION
-------     ------------------------------------------------
 [1]        DllName.  If this element is a NIL, then the
            pointer must be linked into the application .EXE.

 [2]        Pointer resource number.  This is a resource number
            in the .DLL or the .EXE.

 [3]        Pointer type. See the :setPointer() method of
            XbpWindow() for more information.

@<lCancel> is used in GUI mode only.  If this argument is passed
as a logical value, a "Cancel" button will be displayed on the
Working dialog box.  If the operator clicks on the Cancel button
the value of <lCancel> will be set to .FALSE.

Examples:

-- Example 1 --

/*
This example displays a working dialog in text mode.
*/

PROCEDURE XTest1()

LOCAL lCancel := .f.

USE COLLECT NEW EXCLUSIVE

DC_Gui(.f.)
DC_WORKING( 0,'Deleting records ',,,,,,,,,@lCancel )
dbSetOrder(0)
go top
do while !Eof() .AND. !lCancel
  DC_WORKING( 1 )
  dbDelete()
  SKIP
enddo
DC_Pause(5)
DC_WORKING( 2 )

RETURN

-- Example 2 --

#include "dccursor.ch"

/*
This example displays a working dialog in GUI mode.  The mouse
pointer is changed to an hour-glass until the dialog is destroyed.
*/

PROCEDURE Xtest2()

USE COLLECT NEW EXCLUSIVE

DC_Gui(.T.)
DC_WORKING( 0,'Deleting records ',,,,,,,,{nil,POINTER_BUSY_1,1})
dbSetOrder(0)
go top
do while !Eof()
  DC_WORKING( 1 )
  dbDelete()
  SKIP
enddo
DC_Pause(5)
DC_WORKING( 2 )

RETURN

Files:

_DCODD2.PRG/.OBJ,DCLIPX.LIB

See Also:

   dc_progress()
   dc_odometer()
   dc_odblock()


DC_WtfEnable()

Get-Set to enable or disable WTF output

DC_WtfEnable() is a Get-Set that is used to enable or disable WTF commands in source code. Too often, WTF commands are inadvertently left in source code and debugging info appears on the screen after deploying an application.<br><br>Example 1: DC_WtfEnable({'DONNAY_TEST','Y'}) will cause WTF output to be displayed only if there is a system environment variable named DONNAY_TEST with a value of Y. The default is to always display WTF output.<br><br>Example 2: DC_WtfEnable( {||UserId()=='RDONNAY'} ) will only allow WTF output if user RDONNAY is logged on.<br><br>

Syntax:

DC_WtfEnable( <abEnable> ) -> abOldEnable

Returns:

An array, a code block or a NIL.

Arguments:

<abEnable> may be a 2 element array of character strings or a code
block.

If abEnable is an array the 2 elements are as follows:

[1] The name of the system environment variable.
[2] The value of the environment variable.

If abEnable is a code block then the code block must return a
logical value.

Files:

_DCQOUT.PRG, DCLIPX.DLL

See Also:

   WTF


dc_xbpgetlbclick()

Post code block to evaluate when mouse in clicked in any DCGET

DC_XbpGetLbClick() is used to post a code block to evaluate when the left mouse button is clicked in any DCGET in the application.

Syntax:

DC_XbpGetLbClick( <bClick> ) -> bPrevClick

Returns:

The previous code block.

Arguments:

<bClick> is a code block to evaluate.

The code block is passed the standard values of mp1, mp2 and oXbp.

Examples:

/* This code block can be used to position the
   mouse cursor to the end of the get. */

DC_XbpGetLbClick( {|x,y,o|GoToEnd(o)} )

STATIC FUNCTION GoToEnd( oGet )

LOCAL nPos := oGet:get:pos
IF nPos > Len(Trim(oGet:buffer))
   PostAppEvent(xbeP_Keyboard,xbeK_END,,oGet)
   PostAppEvent(xbeP_Keyboard,xbeK_END,,oGet)
ENDIF

RETURN nil

Files:

_DCXBPGT.PRG, DCLIPX.DLL


dc_xbpgetpres()

Set the default presentation parameters for the DC_XbpGet() class

DC_XPPGETPRES() is used to set the default presentation parameters for the DC_XbpGet() class. This includes @ DCSAY..GET and @ DCGET commands.<br><br>

Syntax:

DC_XbpGetPres( [<aPres>] ) -> aPres

Returns:

An array containing the current default setting.

Arguments:

<aPres> is an array of presentation parameters that conforms to
the specification for the XbpSle() class.

Examples:

// Set the color of disabled objects.

aPres :={ { XBP_PP_DISABLED_FGCLR,GRA_CLR_WHITE},;
          { XBP_PP_DISABLED_BGCLR,GRA_CLR_PALEGRAY}}

DC_XbpGetPres(aPres)

Files:

_DCXBPGT.PRG, DCLIPX.DLL

See Also:

   @ DCGET


dc_xbpmenuconfig()

A Get-Set function for configuring OwnerDraw menus

DC_XbpMenuConfig() is used to configure the OwnerDraw options for menus when using the OWNERDRAW clause of DCMENUBAR or DCSUBMENU.<br><br>

Syntax:

DC_XbpMenuConfig( [<aConfig> ] ) -> aOldConfig

Arguments:

<aConfig> is an array of 12 elements:

Element   Type    Description
-------   ----    ---------------------------------------------
  [1]      A/N    Default Background color of pulldown sub menus

  [2]      A/N    Default Foreground color of Vertical Bartext
                  area of sub menus.

  [3]      A/N    Default Background color of Vertical Bartext area

  [4]      A/N    Default Color of menu outline.

  [5]      C      Default compound font name of the Vertical Bartext
                  are of sub menus.

  [6]      L/Nil  A logical .TRUE. to enable the OwnerDraw feature
                  A logical .FALSE. to disable the OwnerDraw feature

  [7]      C      Default compound font name of the check character
                  to use when a sub menu item is checked.

  [8]      C      Default single character to use for the check when
                  a sub menu item is checked.

  [9]      A/N    Default MenuBar Foreground Color.

  [10]     A/N    Default MenuBar Background Color.

  [11]     A/N    Default Foreground color of pulldown sub menus

  [12]     C      Default compound font name of the Menubar.

Files:

_dcclass.prg, dclipx.lib, dclipx.dll

See Also:

   DCMENUBAR
   DCSUBMENU


dc_xbpmenushift()

Get-Set to post a codeblock to call when shift key held down on a menu

DC_XbpMenuShift() is a Get-Set function: DC_XbpMenuShift(). This is used to post a codeblock to call when the shift key is held down while clicking a menu item. This is a handy feature to make it easy to give users the ability to create their own shortcuts from any existing menu system.<br><br>

Syntax:

DC_XbpMenuShift( [<bEval>,NIL] -> bOldEval

Returns:

A code block or a NIL.

Arguments:

<bEval> is a code block to evaluate when a menu selection is made with the SHIFT key.

Examples:

See the example program in \exp19\samples\menu\menushortcuts.prg

Files:

_DCCLASS.PRG

See Also:

   DCMENUITEM
   DCSUBMENU


dc_xbppushbuttonxpdefault()

Get or Set the default style for DC_XbpPushButtonXP() push buttons

DC_XbpPushButtonXPDefault() is a Get-Set function that is used to Set or Get the default configuration object for XP style pushbuttons.

Syntax:

DC_XbpPushButtonXPDefault( [<oConfig>] ) -> oOldConfig

Arguments:

<oConfig> is an object of the DC_XbpPushButtonXPConfig() class.

Examples:

oConfig := DC_XbpPushButtonXPConfig():new()

oConfig:radius := 20
oConfig:bgColor := GRA_CLR_CYAN

DC_XbpPushButtonXPDefault( oConfig )

Files:

_dcxbutt.prg, dclipx.dll

See Also:

   @ DCPUSHBUTTONXP
   dc_xbppushbuttonxpconfig()


dc_xbptohtmlcolor()

Convert XBP colors to HTML colors

DC_XbpToHtmlColor() is used to convert Xbase++ GRA_CLR* colors or RGB colors to #xxxxxx color strings that are used in web applications.

Syntax:

DC_XbpToHtmlColor( <naColor> ) -> cHtmlColor

Returns:

A character string.

Arguments:

<naColor> may be either a numeric color value as defined in
GRA.CH or an array of 3 numeric elements containing RGB
colors.

Examples:

? DC_XbpToHtmlColor( GRA_CLR_GREEN )
#00FF00

? DC_XbpToHtmlColor( { 255, 255, 255 } )
#FFFFFF

Files:

_DCHTML.PRG

See Also:

   dc_readhtml()


dc_xcarray()

Return an Array Template for X2CLIP interface

DC_XCARRAY() returns an array which is later passed to DC_XCCALL(). The array contains information which is passed to the X2CLIP.EXE program needed to perform requested database operations. This information includes file names, index keys, conditions, etc.<br><br> The definitions of the array elements are contained in DCXTOC.CH.<br><br> Element Purpose -------------------- -------------------------------------------- XC_ARRAY_OPERATION Operation Type : XC_OPENDATA - Open Database XC_OPENINDEX - Open Index file XC_CREATEINDEX - Create Index XC_CLOSEDATA - Close Database XC_COPYDATA - Copy a Database XC_PROGRAM - Run Custom Program XC_ARRAY_DEFAULT Value for SET DEFAULT (database directory) XC_ARRAY_DATABASE Name of Database XC_ARRAY_INDEX Name of Index File XC_ARRAY_RDD Name of RDD to use XC_ARRAY_SHARED Logical .TRUE. if file is opened Shared XC_ARRAY_TAG Name of Index Tag to select or create XC_ARRAY_KEY Name of Index Key (for creating indexes) XC_ARRAY_RECORD Starting Record XC_ARRAY_WHILE WHILE Clause XC_ARRAY_FOR FOR Clause XC_ARRAY_EVERY EVERY Value XC_ARRAY_DATE Reserved XC_ARRAY_TIME Reserved XC_ARRAY_ERRORCODE Reserved XC_ARRAY_UNIQUE Logical .TRUE. if index is Unique XC_ARRAY_DESCEND Logical .TRUE. if index is Descending XC_ARRAY_CURRCOUNT Reserved XC_ARRAY_MESSAGE Reserved XC_ARRAY_DATA An array of data to transfer (CARGO). This array is passed as a parameter to the program defined in XC_ARRAY_PROGRAM. XC_ARRAY_PROGRAM Program to Run XC_ARRAY_VERBOSE Logical .TRUE. if X2CLIP.EXE displays status messages. XC_ARRAY_INTERPRET Reserved XC_ARRAY_ACTIVE Reserved XC_ARRAY_DONE Reserved XC_ARRAY_MAXCOUNT Reserved XC_ARRAY_USER1 User Field 1 (up to 254 characters) XC_ARRAY_USER2 User Field 2 (up to 254 characters) XC_ARRAY_USER3 User Field 3 (up to 254 characters) XC_ARRAY_USER4 User Field 4 (up to 254 characters) XC_ARRAY_NEXT Numeric value (NEXT clause) XC_ARRAY_REST Logical Value (REST clause)<br><br>

Syntax:

DC_XCArray() -> aParams

Returns:

 An array.

Arguments:

<nHandle> is the handle previously returned by DC_XCOpen() when
opening the X2CLIP session.

<aParams> is an array of parameters that is passed to the X2CLIP
program.  A template for this array is returned by DC_XCArray().
Individual elements are set to required values depending on the
operation required by the X2CLIP.EXE program.  Defines for this
array are contained in DCXTOC.CH.

<bEval> is an optional code block to evaluate in a loop.  The
loop runs continuously until a message is received from the
X2CLIP.EXE program that the requested task is complete.  The
code block should be constructed as follows:

    {| nCurr, nMax | ... }

    <nCurr> is the current value returned by the X2CLIP.EXE
    program.  Usually this is a record pointer such as RecNo().
    <nMax> is the maximum value returned by the X2CLIP.EXE
    program.  Usually this is the total number of records such
    as RecCount().  These values are constantly updated by a
    call to DC_XCUpdate() which is part of the Clipper program.

<nSleep> is the amount of time to Sleep in the loop between
calls to evaluate <bEval>.  The default is 5, where the number
represents 1/100 of a second.

@<aReturn> is the name of a variable which will receive an array
of data returned by the X2CLIP.EXE program.  This array is
returned by a call to DC_XCReturn() which is part of the Clipper
program.

Examples:

#include "dcxtoc.ch"

PROCEDURE XTest()

/*
This example demonstrates a re-indexing
progress bar which using the X2CLIP interface.
This interface spawns a Clipper
program to create the index.
*/

LOCAL aParams, nHandle, lStatus := .t., aIndex, oDlg, ;
      oSay, oProgress, bEval, lOk := .t., GetList := {}, ;
      i, nSeconds

nHandle := DC_XCOpen()
IF nHandle <= 0
  RETURN .f.
ENDIF

@ 1,1 DCSAY 'Creating Indexes'
@ 2,1 DCSAY '' SAYOBJECT oSay SAYSIZE 40
@ 4,1 DCPROGRESS oProgress SIZE 40,1.2 ;
      COLOR GRA_CLR_RED PERCENT ;
      EVERY IIF( nMode=1,100,1 )

DCREAD GUI EXIT FIT PARENT @oDlg ;
   TITLE "Indexing Example"

BEGIN SEQUENCE

aParams := DC_XCARRAY()
aParams[XC_ARRAY_DEFAULT] := 'C:\express\sample'
aParams[XC_ARRAY_DATABASE] := 'XTEST.DBF'
aParams[XC_ARRAY_RDD] := 'DBFCDX'
aParams[XC_ARRAY_OPERATION] := XC_OPENDATA
IF !DC_XCCALL( nHandle, aParams )
  lOk := .f.
  BREAK
ENDIF

aIndex := { ;
   { 'AREACODE','AREACODE',nil,.f.,.f.}, ;
   { 'EXCHANGE','EXCHANGE',nil,.f.,.f.}, ;
   { 'CITY',    'CITY',nil,.f.,.f.}      ;
  }

bEval := {|nCurr,nMax|DC_GetProgress(oProgress,nCurr,nMax)}

nSeconds := Seconds()

FOR i := 1 TO Len(aIndex)
  oSay:setCaption('Creating Tag ' + aIndex[i,2])
  aParams := DC_XCARRAY()
  aParams[XC_ARRAY_DEFAULT] := 'C:\express\sample'
  aParams[XC_ARRAY_INDEX] := 'XTEST.CDX'
  aParams[XC_ARRAY_OPERATION] := XC_CREATEINDEX
  aParams[XC_ARRAY_TAG] := aIndex[i,1]
  aParams[XC_ARRAY_KEY] := aIndex[i,2]
  aParams[XC_ARRAY_FOR] := aIndex[i,3]
  aParams[XC_ARRAY_UNIQUE] := aIndex[i,4]
  aParams[XC_ARRAY_DESCEND] := aIndex[i,5]
  IF !DC_XCCALL( nHandle, aParams, bEval, 5 )
    lOk := .f.
    BREAK
  ENDIF
NEXT

END SEQUENCE

oDlg:Destroy()

DC_XCClose( nHandle )

RETURN lOk

Files:

_DCXTOC.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_xccall()


dc_xccall()

Send a message to X2CLIP to perform an operation

DC_XCCALL() is used to send data to the X2CLIP.EXE program which is running in the background with information about database or custom operations to perform.<br><br> DC_XCCALL() stays in a loop until the XCLIP2.EXE program sends a message that it is done with the requested task. While in the loop, an optional code block is continuously evaluated to update status in the Xbase++ program such as progress bars.

Syntax:

DC_XCCall( <nHandle>, ;
           <aParams>, ;
           [<bEval>], ;
           [<nSleep>], ;
           [@<aReturn>], ;
           [<lErrorMsg>] ) -> lStatus

Returns:

 A logical .TRUE. if the call was successful, .FALSE. otherwise.

Arguments:

<nHandle> is the handle previously returned by DC_XCOpen() when
opening the X2CLIP session.

<aParams> is an array of parameters that is passed to the X2CLIP
program.  A template for this array is returned by DC_XCArray().
Individual elements are set to required values depending on the
operation required by the X2CLIP.EXE program.  Defines for this
array are contained in DCXTOC.CH.

<bEval> is an optional code block to evaluate in a loop.  The
loop runs continuously until a message is received from the
X2CLIP.EXE program that the requested task is complete.  The
code block should be constructed as follows:

    {| nCurr, nMax, nEvery, aData | ... }

    <nCurr> is the current value returned by the X2CLIP.EXE
    program.  Usually this is a record pointer such as RecNo().
    <nMax> is the maximum value returned by the X2CLIP.EXE
    program.  Usually this is the total number of records such
    as RecCount().  <nEvery> is how often the status bars or
    messages should be updated.  <aData> is an array of data.
    These values are constantly updated by a call to DC_XCUpdate()
    which is part of the Clipper program.

<nSleep> is the amount of time to Sleep in the loop between
calls to evaluate <bEval>.  The default is 5, where the number
represents 1/100 of a second.

@<aReturn> is the name of a variable which will receive an array
of data returned by the X2CLIP.EXE program.  This array is
returned by a call to DC_XCReturn() which is part of the Clipper
program.  If an error occurred in the X2CLIP.EXE program, then
<aReturn> will contain an array of 4 elements:

 Element   Type  Description
 --------  ---- ---------------------------------------------
  [1]        N   DOS Error Number
  [2]        C   File Name
  [3]        C   Error Description
  [4]        C   More info (if available)

<lErrorMsg> if .TRUE. will display the error information in
<aReturn>.  The default is .FALSE.

Examples:

#include "dcxtoc.ch"

PROCEDURE XTest()

/*
This example demonstrates a re-indexing
progress bar which uses the X2CLIP interface.
This interface spawns a Clipper
program to create the index.
*/

LOCAL aParams, nHandle, lStatus := .t., aIndex, oDlg, ;
      oSay, oProgress, bEval, lOk := .t., GetList := {}, ;
      i, nSeconds

nHandle := DC_XCOpen()
IF nHandle <= 0
  RETURN .f.
ENDIF

@ 1,1 DCSAY 'Creating Indexes'
@ 2,1 DCSAY '' SAYOBJECT oSay SAYSIZE 40
@ 4,1 DCPROGRESS oProgress SIZE 40,1.2 ;
      COLOR GRA_CLR_RED PERCENT ;
      EVERY IIF( nMode=1,100,1 )

DCREAD GUI EXIT FIT PARENT @oDlg ;
   TITLE "Indexing Example"

BEGIN SEQUENCE

aParams := DC_XCArray()
aParams[XC_ARRAY_DEFAULT] := 'C:\express\sample'
aParams[XC_ARRAY_DATABASE] := 'XTEST.DBF'
aParams[XC_ARRAY_RDD] := 'DBFCDX'
aParams[XC_ARRAY_OPERATION] := XC_OPENDATA
IF !DC_XCCALL( nHandle, aParams )
  lOk := .f.
  BREAK
ENDIF

aIndex := { ;
   { 'AREACODE','AREACODE',nil,.f.,.f.}, ;
   { 'EXCHANGE','EXCHANGE',nil,.f.,.f.}, ;
   { 'CITY',    'CITY',nil,.f.,.f.}      ;
  }

bEval := {|nCurr,nMax|DC_GetProgress(oProgress,nCurr,nMax)}

nSeconds := Seconds()

FOR i := 1 TO Len(aIndex)
  oSay:setCaption('Creating Tag ' + aIndex[i,2])
  aParams := DC_XCArray()
  aParams[XC_ARRAY_DEFAULT] := 'C:\express\sample'
  aParams[XC_ARRAY_INDEX] := 'XTEST.CDX'
  aParams[XC_ARRAY_OPERATION] := XC_CREATEINDEX
  aParams[XC_ARRAY_TAG] := aIndex[i,1]
  aParams[XC_ARRAY_KEY] := aIndex[i,2]
  aParams[XC_ARRAY_FOR] := aIndex[i,3]
  aParams[XC_ARRAY_UNIQUE] := aIndex[i,4]
  aParams[XC_ARRAY_DESCEND] := aIndex[i,5]
  IF !DC_XCCALL( nHandle, aParams, bEval, 5 )
    lOk := .f.
    BREAK
  ENDIF
NEXT

END SEQUENCE

oDlg:Destroy()

DC_XCClose( nHandle )

RETURN lOk

Files:

_DCXTOC.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_xcopen()
   dc_xcarray()


dc_xcclose()

Close an X2CLIP session

DC_XCCLOSE() is used to close an X2CLIP session previously opened by DC_XCOPEN(). This will send a message to the X2CLIP.EXE program to close all files and terminate.<br><br>

Syntax:

DC_XCClose ( <nHandle> ) -> lStatus

Returns:

 A numeric file handle to be used by the other DC_TXT*()
 functions.

Arguments:

<nHandle> is the handle returned by DC_XCOpen().

Examples:

#include "dcxtoc.ch"

PROCEDURE XTest()

/*
This example demonstrates a re-indexing
progress bar which using the X2CLIP interface.
This interface spawns a Clipper
program to create the index.
*/

LOCAL aParams, nHandle, lStatus := .t., aIndex, oDlg, ;
      oSay, oProgress, bEval, lOk := .t., GetList := {}, ;
      i, nSeconds

nHandle := DC_XCOpen()
IF nHandle <= 0
  RETURN .f.
ENDIF

@ 1,1 DCSAY 'Creating Indexes'
@ 2,1 DCSAY '' SAYOBJECT oSay SAYSIZE 40
@ 4,1 DCPROGRESS oProgress SIZE 40,1.2 ;
      COLOR GRA_CLR_RED PERCENT ;
      EVERY IIF( nMode=1,100,1 )

DCREAD GUI EXIT FIT PARENT @oDlg ;
   TITLE "Indexing Example"

BEGIN SEQUENCE

aParams := DC_XCArray()
aParams[XC_ARRAY_DEFAULT] := 'C:\express\sample'
aParams[XC_ARRAY_DATABASE] := 'XTEST.DBF'
aParams[XC_ARRAY_RDD] := 'DBFCDX'
aParams[XC_ARRAY_OPERATION] := XC_OPENDATA
IF !DC_XCCall( nHandle, aParams )
  lOk := .f.
  BREAK
ENDIF

aIndex := { ;
   { 'AREACODE','AREACODE',nil,.f.,.f.}, ;
   { 'EXCHANGE','EXCHANGE',nil,.f.,.f.}, ;
   { 'CITY',    'CITY',nil,.f.,.f.}      ;
  }

bEval := {|nCurr,nMax|DC_GetProgress(oProgress,nCurr,nMax)}

nSeconds := Seconds()

FOR i := 1 TO Len(aIndex)
  oSay:setCaption('Creating Tag ' + aIndex[i,2])
  aParams := DC_XCArray()
  aParams[XC_ARRAY_DEFAULT] := 'C:\express\sample'
  aParams[XC_ARRAY_INDEX] := 'XTEST.CDX'
  aParams[XC_ARRAY_OPERATION] := XC_CREATEINDEX
  aParams[XC_ARRAY_TAG] := aIndex[i,1]
  aParams[XC_ARRAY_KEY] := aIndex[i,2]
  aParams[XC_ARRAY_FOR] := aIndex[i,3]
  aParams[XC_ARRAY_UNIQUE] := aIndex[i,4]
  aParams[XC_ARRAY_DESCEND] := aIndex[i,5]
  IF !DC_XCCall( nHandle, aParams, bEval, 5 )
    lOk := .f.
    BREAK
  ENDIF
NEXT

END SEQUENCE

oDlg:Destroy()

DC_XCCLOSE( nHandle )

RETURN lOk

Files:

_DCXTOC.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_xcopen()


dc_xcopen()

Open an X2CLIP session for database operations

DC_XCOPEN() is used to open an X2CLIP session for database operations. The X2CLIP interface is an API that uses a Clipper program which is run in the background and synchronized with the Xbase++ program to perform database operations faster than the Xbase++ DBE system.<br><br> DC_XCOpen() opens X2CLIP.DBF in shared mode and searches for an inactive record. This record becomes the "handle" of the information workspace which is used to pass information between the Xbase++ program and the Clipper program. The handle is passed to X2CLIP.EXE which is launched in the background. The X2CLIP.EXE program then runs a main loop which waits for instructions based on calls to DC_XCCall(). Instructions can include anything from opening databases and indexes or creating indexes to running any custom program linked into X2CLIP.EXE. The X2CLIP.EXE runs until it receives an instruction to terminate by calling DC_XCClose().<br><br> X2CLIP.EXE sends information back to the Xbase++ program about its current status such as pointers needed for updating progress bars. <br><br>

Syntax:

DC_XCOpen ( [<nTimeOut>], ;
            [<lErrorMsg>], ;
            [<cExeName>] ) -> nHandle

Returns:

 A numeric file handle to be used by the other DC_XC*() functions.
 If communication could not be established with X2CLIP.EXE the
 value 0 will be returned.

Arguments:

<nTimeOut> is the timeout (in seconds) to establish a
communcation with the X2CLIP.EXE program.  The default is 5
seconds.  If no communication is established within the timeout
period, DC_XCOPEN() will return a valid handle otherwise it will
return 0.

<lErrorMsg> if .TRUE. will display a message in the event that
communication could not be established.  The default is .FALSE.

<cExeName> is the name of the Clipper EXEcutable program.  The
default is X2CLIP.EXE.

Notes:

If X2CLIP.DBF does not exist it will be created in the DEFAULT directory of the Xbase++ program. The default directory is passed to the X2CLIP.EXE program to insure that the same X2CLIP.DBF is used by the Clipper program.

Examples:

#include "dcxtoc.ch"

PROCEDURE XTest()

/*
This example demonstrates a re-indexing
progress bar which using the X2CLIP interface.
This interface spawns a Clipper
program to create the index.
*/

LOCAL aParams, nHandle, lStatus := .t., aIndex, oDlg, ;
      oSay, oProgress, bEval, lOk := .t., GetList := {}, ;
      i, nSeconds

nHandle := DC_XCOPEN()
IF nHandle <= 0
  RETURN .f.
ENDIF

@ 1,1 DCSAY 'Creating Indexes'
@ 2,1 DCSAY '' SAYOBJECT oSay SAYSIZE 40
@ 4,1 DCPROGRESS oProgress SIZE 40,1.2 ;
      COLOR GRA_CLR_RED PERCENT ;
      EVERY IIF( nMode=1,100,1 )

DCREAD GUI EXIT FIT PARENT @oDlg ;
   TITLE "Indexing Example"

BEGIN SEQUENCE

aParams := DC_XCArray()
aParams[XC_ARRAY_DEFAULT] := 'C:\express\sample'
aParams[XC_ARRAY_DATABASE] := 'XTEST.DBF'
aParams[XC_ARRAY_RDD] := 'DBFCDX'
aParams[XC_ARRAY_OPERATION] := XC_OPENDATA
IF !DC_XCCall( nHandle, aParams )
  lOk := .f.
  BREAK
ENDIF

aIndex := { ;
   { 'AREACODE','AREACODE',nil,.f.,.f.}, ;
   { 'EXCHANGE','EXCHANGE',nil,.f.,.f.}, ;
   { 'CITY',    'CITY',nil,.f.,.f.}      ;
  }

bEval := {|nCurr,nMax|DC_GetProgress(oProgress,nCurr,nMax)}

nSeconds := Seconds()

FOR i := 1 TO Len(aIndex)
  oSay:setCaption('Creating Tag ' + aIndex[i,2])
  aParams := DC_XCArray()
  aParams[XC_ARRAY_DEFAULT] := 'C:\express\sample'
  aParams[XC_ARRAY_INDEX] := 'XTEST.CDX'
  aParams[XC_ARRAY_OPERATION] := XC_CREATEINDEX
  aParams[XC_ARRAY_TAG] := aIndex[i,1]
  aParams[XC_ARRAY_KEY] := aIndex[i,2]
  aParams[XC_ARRAY_FOR] := aIndex[i,3]
  aParams[XC_ARRAY_UNIQUE] := aIndex[i,4]
  aParams[XC_ARRAY_DESCEND] := aIndex[i,5]
  IF !DC_XCCall( nHandle, aParams, bEval, 5 )
    lOk := .f.
    BREAK
  ENDIF
NEXT

END SEQUENCE

oDlg:Destroy()

DC_XCClose( nHandle )

RETURN lOk

Files:

_DCXTOC.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_xcclose()


dc_xcreturn()

Return data from the X2CLIP program

DC_XCRETURN() is used in the X2CLIP.EXE program to return an array of information to the Xbase++ program via the DC_XCCall() function.<br><br>

Syntax:

DC_XCReturn( <aArray> ) -> nil

Returns:

 Nil.

Arguments:

<aArray> is an array of information to return.  This array may
contain any values except objects and code blocks.

Notes:

DC_XCRETURN() is only used if the operation requested by a DC_XCCall() is an XC_PROGRAM.

Examples:

#include "dcxtoc.ch"

/*

This example demonstrates how to use the Xbase to
Clipper interface to improve performance of
database operations.  The procedure XTEST() is
contained in the Xbase++ application.  The
procedure XCLIP60() is contained in the X2CLIP.EXE
program.

*/

PROCEDURE XTest()

LOCAL oProgress, GetList := {}, ;
      i, nSeconds, dDate := Date(), cAreaCode := '777', ;
      lReplacing := .f., oButton

@ 2,1 DCSAY 'This routine will replace the date field with'

@ 3,1 DCSAY 'the entered value for the selected area code.'

@ 5,1 DCSAY ' New Date' GET dDate POPUP {|d|DC_PopDate(d)}

@ 6,1 DCSAY 'Area Code' GET cAreaCode PICT '999' WHEN {||.f.}

@ 8,1 DCPROGRESS oProgress SIZE 40,1.2 ;
      COLOR GRA_CLR_RED PERCENT ;
      EVERY IIF( lX2Clip,1,100 )

@ 8,45 DCPUSHBUTTON CAPTION 'Replace' OBJECT oButton ;
      SIZE 9,1.2 ;
      ACTION {||_XSample60( oProgress, oButton, ;
                            @lReplacing, dDate, cAreaCode, ;
                            GetList ) } ;
      WHEN {||!lReplacing}

DCREAD GUI FIT ADDBUTTONS ;
   TITLE "Database Operation Example"

RETURN nil

/* ----------------------- */

STATIC FUNCTION _XTest( oProgress, oButton, ;
                        lReplacing, dDate, cAreaCode, ;
                        GetList )

LOCAL nSeconds, nHandle, aData, bEval, aParams, aReturn, ;
      nRecords := 0

BEGIN SEQUENCE

lReplacing := .t.
DC_GetRefresh(GetList)
CLOSE ALL
nSeconds := Seconds()

nHandle := DC_XCOpen()
IF nHandle <= 0
  BREAK
ENDIF
aData := { '\express\sample', 'XTEST.DBF', 'XTEST.CDX', ;
           'DBFCDX', dDate, cAreaCode }
bEval := {|nCurr,nMax|DC_GetProgress(oProgress,nCurr,nMax)}
aParams := DC_XCArray()
aParams[XC_ARRAY_OPERATION] := XC_PROGRAM
aParams[XC_ARRAY_PROGRAM]   := 'XClip60'
aParams[XC_ARRAY_DATA]      := aData
IF !DC_XCCall( nHandle, aParams, bEval, 5, @aReturn )
  BREAK
ENDIF
DC_XCClose(nHandle)
nRecords := aReturn[1]
DC_GetProgress(oProgress,100,100)

DC_MsgBox({ Alltrim(Str(nRecords)) + ' records updated.', ;
            'Update time: ' +  ;
             Alltrim(Str(Seconds()-nSeconds)) + ' seconds!' })

END SEQUENCE
lReplacing := .f.

RETURN nil

/* ------------------- */

* Part of X2CLIP.EXE

FUNCTION XClip60( aData )

LOCAL cDefault, cDatabase, cIndex, cRdd, dDate, cAreaCode, ;
      nRecords := 0

cDefault  := aData[1]
cDatabase := aData[2]
cIndex    := aData[3]
cRdd      := aData[4]
dDate     := aData[5]
cAreaCode := aData[6]

SET DEFAULT TO (cDefault)
USE (cDatabase) SHARED VIA cRdd ALIAS XTEST

GO TOP
DO WHILE !Eof()
  IF XTEST->areacode == cAreaCode
     IF _RecLock(5)
       REPL XTEST->date WITH DTOC(dDate)
       nRecords++
       COMMIT
       UNLOCK
     ENDIF
  ENDIF
  DC_XCUpdate( RecNo(), RecCount(), 100 )
  SKIP
ENDDO
CLOSE

DC_XCRETURN( { nRecords } )

RETURN nil

Files:

X2CLIP.PRG/.OBJ, X2CLIP.EXE

See Also:

   dc_xcopen()
   dc_xccall()


dc_xcupdate()

Update pointers in the X2CLIP program

DC_XCUPDATE() is used in the X2CLIP.EXE program to update database pointers and return data which is passed back to the Xbase++ program for eveluation by DC_XCCALL().<br><br> This function is called regularly during the required database operation in the X2CLIP.EXE program to insure that status indicators in the Xbase++ program are constantly updated or to pass back an array of information.<br><br>

Syntax:

DC_XCUpdate( [<nCurr>], ;
             [<nMax>], ;
             [<nEvery>], ;
             [<aData>] ) -> nil

Returns:

 A numeric file handle to be used by the other DC_TXT*()
 functions.

Arguments:

<nCurr> is the current pointer.  The default is RecNo().

<nMax> is the maximum count.  The default is RecCount().

<nEvery> is how often the count should be updated.  The default
is 1.  This number should be a rather high number to improve
performance because the current information can only be passed
back to the Xbase++ program by locking and updating the record
in X2CLIP.DBF associated with this session.   For example, to
insure that a progress bar in the Xbase++ application gets updated
every 1% <nEvery> would be set to Int(RecCount()/100).

<aData> is an array of any information.  The array may be multi-
dimensional but may not contain Code-Blocks or Objects.

Notes:

DC_XCUPDATE() is only used if the operation requested by a DC_XCCall() is an XC_PROGRAM, otherwise the update is handled automatically.

Examples:

#include "dcxtoc.ch"

/*

This example demonstrates how to use the Xbase to
Clipper interface to improve performance of
database operations.  The procedure XTEST() is
contained in the Xbase++ application.  The
procedure XCLIP60() is contained in the X2CLIP.EXE
program.

*/

PROCEDURE XTest()

LOCAL oProgress, GetList := {}, ;
      i, nSeconds, dDate := Date(), cAreaCode := '777', ;
      lReplacing := .f., oButton

@ 2,1 DCSAY 'This routine will replace the date field with'

@ 3,1 DCSAY 'the entered value for the selected area code.'

@ 5,1 DCSAY ' New Date' GET dDate POPUP {|d|DC_PopDate(d)}

@ 6,1 DCSAY 'Area Code' GET cAreaCode PICT '999' WHEN {||.f.}

@ 8,1 DCPROGRESS oProgress SIZE 40,1.2 ;
      COLOR GRA_CLR_RED PERCENT ;
      EVERY IIF( lX2Clip,1,100 )

@ 8,45 DCPUSHBUTTON CAPTION 'Replace' OBJECT oButton ;
      SIZE 9,1.2 ;
      ACTION {||_XSample60( oProgress, oButton, ;
                            @lReplacing, dDate, cAreaCode, ;
                            GetList ) } ;
      WHEN {||!lReplacing}

DCREAD GUI FIT ADDBUTTONS ;
   TITLE "Database Operation Example"

RETURN nil

/* ----------------------- */

STATIC FUNCTION _XTest( oProgress, oButton, ;
                        lReplacing, dDate, cAreaCode, ;
                        GetList )

LOCAL nSeconds, nHandle, aData, bEval, aParams, aReturn, ;
      nRecords := 0

BEGIN SEQUENCE

lReplacing := .t.
DC_GetRefresh(GetList)
CLOSE ALL
nSeconds := Seconds()

nHandle := DC_XCOpen()
IF nHandle <= 0
  BREAK
ENDIF
aData := { '\express\sample', 'XTEST.DBF', 'XTEST.CDX', ;
           'DBFCDX', dDate, cAreaCode }
bEval := {|nCurr,nMax|DC_GetProgress(oProgress,nCurr,nMax)}
aParams := DC_XCArray()
aParams[XC_ARRAY_OPERATION] := XC_PROGRAM
aParams[XC_ARRAY_PROGRAM]   := 'XClip60'
aParams[XC_ARRAY_DATA]      := aData
IF !DC_XCCall( nHandle, aParams, bEval, 5, @aReturn )
  BREAK
ENDIF
DC_XCClose(nHandle)
nRecords := aReturn[1]
DC_GetProgress(oProgress,100,100)

DC_MsgBox({ Alltrim(Str(nRecords)) + ' records updated.', ;
            'Update time: ' +  ;
             Alltrim(Str(Seconds()-nSeconds)) + ' seconds!' })

END SEQUENCE
lReplacing := .f.

RETURN nil

/* ------------------- */

* Part of X2CLIP.EXE

FUNCTION XClip60( aData )

LOCAL cDefault, cDatabase, cIndex, cRdd, dDate, cAreaCode, ;
      nRecords := 0

cDefault  := aData[1]
cDatabase := aData[2]
cIndex    := aData[3]
cRdd      := aData[4]
dDate     := aData[5]
cAreaCode := aData[6]

SET DEFAULT TO (cDefault)
USE (cDatabase) SHARED VIA cRdd

GO TOP
DO WHILE !Eof()
  IF XTEST->areacode == cAreaCode
     IF _RecLock(5)
       REPL XTEST->date WITH DTOC(dDate)
       nRecords++
       COMMIT
       UNLOCK
     ENDIF
  ENDIF
  DC_XCUPDATE( RecNo(), RecCount(), 100 )
  SKIP
ENDDO
CLOSE

DC_XCReturn( { nRecords } )

RETURN nil

Files:

X2CLIP.PRG/.OBJ, X2CLIP.EXE

See Also:

   dc_xcopen()
   dc_xccall()


dc_xml2objecttree()

Create an object tree from an XML file or stream

DC_Xml2ObjectTree() is used to create an object tree that is a hierarchy of DC_XmlNode() objects. An object tree can be used to modify the XML, print XML data, export to an array, etc.

Syntax:

DC_Xml2ObjectTree( <cXml>, ;
                   [<lXb2Net>] ) -> oXmlTree

Returns:

An object.

Arguments:

<cXml> contains either the fully qualified name of a file that
contains only XML data, or an XML data stream in the form of a
string.

<lXb2Net> is an optional parameter that uses the Xb2.Net XML parser
instead of the ASXML parser.  This can occasionally prevent IDSC
errors.  NOTE: The Xb2.Net function xbXML2Array() must be linked
into the program.

Notes:

This function calls XML*() functions from the Alaska SoftwareXML parser, therefore when DCXML.DLL is loaded, it must also loadAlaska's ASXML10.DLL.

Examples:

oTree := DC_Xml2ObjectTree( 'c:\test\test.xml' )

DC_ArrayView(oTree)

Files:

_DCXML.PRG, DCXML.DLL

See Also:

   dc_xmlnode()


dc_xorbits()

A logical EXCLUSIVE OR of two numbers

DC_XORBITS() will produce the result of logically EXCLUSIVE OR of two numbers.<br><br>

Syntax:

DC_XorBits( <nNum1>, ;
            <nNum2> ) ->nResult

Returns:

 A numeric value from 0 - 255

Arguments:

<nNum1> and <nNum2> are numeric values from 0 to 255.

Files:

_DCAND.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_bittest()
   dc_andbits()


dc_xorbitslong()

Exclusive OR on 2 long integer (32 bit values) values

DC_XorBitsLong() performs an exclusive OR on 2 long integer (32 bit values) values.<br><br>

Syntax:

DC_XorBitsLong( <nDecimal1>, ;
                <nDecimal2> ) -> nDecimal

Returns:

A decimal number.

Arguments:

<nDecimal1> and <nDecimal2> are numeric values from 0 to 4294967295.

Files:

_DCFUNCT.PRG/.OBJ, DCLIPX.LIB

See Also:

   dc_dec2longint()


dc_xorstrings()

An Exclusive OR (XOR) of 2 input strings of equal length

DC_XORStrings() will return a string that is an Exclusive OR (XOR) of 2 input strings of equal length.<br><br><br><br>

Syntax:

DC_XorStrings( <cString1>, ;
               <cString2> ) -> cResult

Returns:

A string.

Arguments:

<cString1> and <cString2> are strings of equal length.

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_xorbits()


dc_xpftoarray()

Load the contents of an .XPF memory file to an array

DC_XPFtoArray() is used to read the contents of an .XPF (memory) file and store it to a 2-dimensional array.

Syntax:

 DC_XPFtoArray( <cMemFileName> ) -> aMemVars

Returns:

 A 2-dimensional array with the following structure:

 Element   Type    Description
 -------   -----   ---------------------------------------
  [1]       C      Memory Variable name
  [2]       C      Memory Variable Type
  [3]       X      Variable contents

Arguments:

<cMemFileName> is the name of the memory file.  If no extension
is given then .XPF is assumed.

Examples:

 . aMem := XPFtoArray('CUSTOMER.XPF')
 . DC_ArrayView(aMem)

Files:

_DCMEM.PRG, DCLIP2.DLL

See Also:


dc_xtoc()

Converts any variable type to a String

DC_XTOC() is used to convert any variable type to a character string.

Syntax:

DC_XtoC( <xValue> ) -> cString

Returns:

 A character string.

Arguments:

<xValue> is any variable type.

Examples:

PROCEDURE XTest( aArray )

FOR i := 1 TO Len(aArray)

  ? DC_XtoC(aArray[i])

NEXT

RETURN nil

Files:

_DCVAL.PRG/.OBJ, DCLIPX.LIB


dc_zap()

Zap the database

DC_Zap() is a front end to the Xbase++ dbZap() function that tests if a file is open exclusive and then prompts the user to reopen it exclusive before Zapping the file. In either case, the user is given the option of cancelling the operation.<br><br>

Syntax:

 DC_Zap() -> lStatus

Returns:

 A logical .TRUE. if the file was successfully Zapped, .FALSE.
 otherwise.

Arguments:

 None.

Examples:

 . USE COLLECT
 . DC_Zap()

Files:

_DCDBPK.PRG, DCLIP1.DLL

See Also:

   ZAP


dc_zoomtransparent()

Zoom a Dialog Window from 0% to 100% Transparency

DC_ZoomTransparent() will cause a dialog window to go from 0% to 100% transparency or from 100% to 0% transparency at a specified time period.

Syntax:

DC_ZoomTransparent( <oDlg>, ;
                    [<nMode>], ;
                    [<nSeconds>] ) -> Nil

Returns:

Nil.

Arguments:

<oDlg> is an object that is derived from the XbpDialog class and
is currently hidden with the :hide() method.

<nMode> if 0 will zoom from 0 to 100.  If 1 will zoom from 100
to 0.

<nSeconds> is the amount of seconds required to complete the
zoom process.

Examples:

Run XDEMO.EXE to see the main window fade in.

Files:

_DCFUNCT.PRG, DCLIPX.DLL

See Also:

   dc_setwindowtransparency()


dc_mapdirections()

Show Driving Directions on Google or MSN Maps

DC_MapDirections() is a class that provides a simple interface for calling the Google, Microsoft, Yahoo or Mapquest Mapping websites to provide driving directions. See the sample program in the .\SAMPLES\MAPDIR directory.

Files:

_DCFUNCT.PRG


dc_adsstatement()

A class for connecting a SQL SELECT cursor to a Work Area

DC_AdsStatement() is used to accept a SQL statement and create a SQL cursor that can be navigated with standard DBE navigation methods, like dbSkip(), dbGotop(), @ DCBROWSE, etc. This uses a new feature of Xbase++ 1.9 that really simplifies the process of using SQL queries in an Xbase++ application. Nothing else is needed except the ADSDBE and Xbase++ 1.9.

Syntax:

DC_AdsStatement():New(<cStatement>) -> oStatement

Notes:

The ADSDBE must be loaded before calling this function.

Examples:

cServer := DC_Path(AppName(.t.)) + 'sample.add'

oSession := DC_AdsSession( cServer )

TEXT INTO cStatement
SELECT * FROM XTEST
ENDTEXT

oStatement := DC_AdsStatement():new(cStatement)
cAlias := oStatement:execute()
Browse()

oStatement:close()
oSession:disConnect()

Files:

_DCADS.PRG, DCLIPX.DLL

See Also:

   dc_adssession()


dc_xbrowse()

A framework class for data-driven browse/edit screens

DC_XBrowse() is a class that allows for easy creation of data-driven browse/edit windows for databases. Windows can be related to other windows either in the same thread or in other threads. Full of handy user-configurable features for building browse/edit screens and saving configurations to an .INI file or registry.<br><br>Example: USE customer oBrowse := DC_XBrowse():new() oBrowse:read()<br><br>Note: There are so many iVars and methods to this class that it will take a good amount of time to complete the documentation.<br><br>Before the docs are completed, there first will be a set of examples completed.<br><br>The samples are located in \exp18\samples\xbrowse.

Files:

_DCXWIN.PRG, DCLIP1.DLL


dc_adsgetsqlstatement()

Returns SQL statement that was used for cursor in a work area

DC_AdsGetSQLStatement() is used to return the SQL statement that was used to create a SQL cursor that was applied to a work area using ADSDBE.

Syntax:

DC_AdsGetSQLStatement() -> cStatement

Arguments:

None

Notes:

The ADSDBE must be loaded before calling this function.

Examples:

cServer := DC_Path(AppName(.t.)) + 'sample.add'

oSession := DC_AdsSession( cServer )

TEXT INTO cStatement
SELECT * FROM XTEST
ENDTEXT

oStatement := DC_AdsStatement():new(cStatement)
cAlias := oStatement:execute()

? DC_AdsGetSQLStatement()

oStatement:close()
oSession:disConnect()

Files:

_DCADS.PRG, DCLIPX.DLL

See Also:

   dc_adsstatement()


dc_bargraph()

A class for creating vertical or horizontal bar graphs

The class DC_BarGraph() creates vertical or horizontal bar graphs.

Syntax:

Documentation is not completed.

See the source code.

Examples:

#include "dcgraph.ch"

FUNCTION SalesGraph()

LOCAL i, aCaption, aBarColor, aData, oGraph, bLbDown, ;
      aGraphData[0], nYear := 2000

aData := { ;
   { {10,-12,40},  ;
     {22,16,20},   ;
     {25,35,11},   ;
     {20,25,88},   ;
     {33,50,-99},  ;
     {45,22,16},   ;
     {57,90,77},   ;
     {31,-44,55},  ;
     {21,60,32},   ;
     {51,11,28},   ;
     {66,30,-19},  ;
     {62,49,73} }, ;
   { {39,-52,50},  ;
     {52,28,30},   ;
     {75,25,31},   ;
     {10,15,-28},   ;
     {63,20,29},  ;
     {35,-72,56},   ;
     {27,-30,37},   ;
     {51,14,-65},  ;
     {21,40,32},   ;
     {61,21,-18},   ;
     {46,40,29},  ;
     {32,59,23} }, ;
   { {20,-2,30},   ;
     {32,6,10},    ;
     {15,25,1},    ;
     {10,15,78},   ;
     {23,40,-89},  ;
     {35,12,6},    ;
     {47,80,67},   ;
     {21,-34,45},  ;
     {11,50,22},   ;
     {41,1,18},    ;
     {56,20,-9},   ;
     {52,39,63} } }

nYear := 2000
_GetGraphData( aGraphData, @nYear, aData )

oGraph := DC_BarGraph():new(,,,{600,400})
oGraph:graphColor := { GRA_CLR_YELLOW, GRA_CLR_BLUE, GRA_CLR_RED, GRA_CLR_GREEN }
oGraph:graphData := aGraphData
oGraph:lbDown := {|a,b|DC_DebugQOut({aGraphData[a,1,b]})}
oGraph:rbDown := oGraph:lbDown
oGraph:textFont := '12.Arial Bold'
oGraph:textColorFG := GRA_CLR_BLACK
oGraph:textColorBG := nil
oGraph:scaleFont := '8.Arial Bold'
oGraph:scaleColorFG := GRA_CLR_BLACK
oGraph:type := DCGRAPH_TYPE_VERTICAL
oGraph:title := 'Year 2001 Medallions'
oGraph:graphTitle := { 'Sales','Expenses','Profit','Eleven' }
oGraph:graphTitleFont := '18.Arial Bold'
oGraph:graphBackgroundColor := GRA_CLR_WHITE
oGraph:scrollRange := 12
oGraph:scrollButtons := .t.

oGraph:create()

RETURN nil

* -------------

STATIC FUNCTION _GetGraphData( aGraphData, nYear, aData )

LOCAL i, nPointer := nYear-1999, aMonths

aMonths := {'Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec'}
ASize(aGraphData,0)

FOR i := 1 TO 12
  AAdd(aGraphData, { aData[nPointer,i], aMonths[i] } )
NEXT

RETURN nil

Files:

_DCGRAPH.PRG, DCGRAPH.CH, DCLIPX.DLL

See Also:

   @ DCBARGRAPH


dc_dbnotify()

A class to provide database triggers

DC_DbNotify() is a class that simplifies the use of the Xbase++ dbRegisterClient() function to provide an easy means to trigger writing of information to a log file, database, debug window, etc. whenever a database operation such as a record update occurs. This is handy to create a log of database updates. See the sample program in \exp19\samples\dbnotify. Note: this class is not yet documented in express.hlp. When eXpress++ users start showing an interest in using this feature, it will be documented.

Files:

_dcfunct.prg, dclipx.dll


dc_html()

A base class for creating any HTML element

DC_Html() is a class for creating HTML elements from a set of properties. The :writeHtml() method returns the source code of the element tag and all of its child elements.<br><br>DC_Html() is the base class for all DC_Html*() classes. All other DC_Html*() classes inherit from DC_Html().<br><br>

Syntax:

DC_Html():new( [ <oParent> ], ;
               <aGetListItem> ) -> self

Returns:

Self

Arguments:

<oParent> is the parent object.  It must be already initialized
and must be of the DC_Html*() class.

<aGetListItem> is the item of the GetList associated with
this class.

Notes:

Parent object may be from any DC_Html*() class.Child objects may be from any DC_Html*() class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Main()

LOCAL i, GetList[0], oTable, oHtml, oParent, cHtml, oMainHtml, ;
      aGetListItem, bBlock

DCTABLE OBJECT oTable ROWS 5 COLS 4
@ 2,3 DCHTML TEXT 'This is some text' PARENT oTable
@ 4,4 DCHTML TEXT 'This is some more text' PARENT oTable

FOR i := 1 TO Len(GetList)
  aGetListItem := GetList[i]
  IF Valtype(bBlock := aGetListItem[bGETLIST_PARENT]) == 'B'
    oParent := Eval(bBlock) // get parent
  ENDIF
  IF aGetListItem[nGETLIST_TYPE] == GETLIST_HTML
    oHtml := DC_Html():new(oParent,aGetListItem)
  ELSEIF aGetListItem[nGETLIST_TYPE] == GETLIST_HTMLTABLE
    oHtml := DC_HtmlTable():new(oParent,aGetListItem)
  ENDIF
  IF Empty(oMainHtml)
    oMainHtml := oHtml
  ENDIF
  IF Valtype(bBlock := aGetListItem[bGETLIST_GROUP]) == 'B'
    Eval(bBlock,oHtml) // anchor object to variable
  ENDIF
NEXT

cHtml := oMainHtml:writeHtml()
MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

_DCHTML.PRG

See Also:

   DCREAD HTML
   DCHTML


dc_htmlbody()

A class for creating an HTML body tag

DC_HtmlBody() is a class for creating the <BODY> tag of an html document.<br><br>The :writeHtml() method returns the source code of the IMG tag.

Syntax:

DC_HtmlBody():new( [ <oParent> ], ;
                   <aGetListItem> ) -> self

Arguments:

<oParent> is the parent object.  It must be already initialized
and must be of the DC_Html*() class.

<aGetListItem> is the item of the GetList associated with
this class.

Notes:

Inherits from DC_Html().Child objects may be from any DC_Html*() class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], oMain, oHtml, oParent, cHtml, oMainHtml, ;
      aGetListItem, bBlock, aClass, oBody

DCHTMLMAIN OBJECT oMain

DCHTMLBODY OBJECT oBody ;
     BACKGROUND "http://donnay-software.com/graphics/expback1.gif" ;
     STYLE "\exp18\html\default.css" ;
     PARENT oMain

DCHTML TEXT MemoRead('\exp18\readme.txt') ;
     STYLE 'PRE' ;
     PARENT oBody

aClass := { { GETLIST_HTMLMAIN, {|o,a|DC_HtmlMain():new(o,a)} }, ;
            { GETLIST_HTMLBODY, {|o,a|DC_HtmlBody():new(o,a)} }, ;
            { GETLIST_HTML    , {|o,a|DC_Html():new(o,a)} } }

FOR i := 1 TO Len(GetList)
  oParent := nil
  aGetListItem := GetList[i]
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_PARENT])) == 'B'
    oParent := Eval(bBlock) // get parent
  ENDIF
  IF (nIndex := AScan( aClass, {|a|a[1]==aGetListItem[nGETLIST_TYPE]} )) > 0
    oHtml := Eval(aClass[nIndex,2],oParent,aGetListItem)
  ENDIF
  IF Empty(oMainHtml)
    oMainHtml := oHtml
  ENDIF
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_GROUP])) == 'B'
    Eval(bBlock,oHtml) // anchor object to variable
  ENDIF
NEXT
cHtml := oMainHtml:writeHtml()
MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

_DCHTML.PRG

See Also:

   DCREAD HTML
   DCHTMLBODY


dc_htmlbrowse()

A class for creating a BROWSE in HTML

DC_HtmlBrowse() is a class for creating HTML tables. The :writeHtml() method returns the source code of the table tag and all of its child elements. Child objects must be of the DC_HtmlColumn() class (1 for each column).<br><br>

Syntax:

DC_HtmlBrowse():new( [ <oParent> ], ;
                     <aGetListItem> ) -> self

Arguments:

<oParent> is the parent object.  It must be already initialized
and must be of the DC_Html*() class.

<aGetListItem> is the item of the GetList associated with
this class.

Notes:

Inherits from DC_Html() and DC_HtmlTable().Parent object may be from any DC_Html*() class.Child objects must be from DC_HtmlColumn() class.

Examples:

/*
This is an example of an array browse
*/

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], oTable, oHtml, oParent, cHtml, oMainHtml, ;
      aGetListItem, bBlock, aDir := Directory()

@ 0,0 DCBROWSE oBrowse SIZE 4,10 DATA aDir

DCBROWSECOL ELEMENT 1 HEADER 'File Name' PARENT oBrowse
DCBROWSECOL ELEMENT 2 HEADER 'File Size' PARENT oBrowse
DCBROWSECOL ELEMENT 3 HEADER 'File Date' PARENT oBrowse
DCBROWSECOL ELEMENT 4 HEADER 'File Time' PARENT oBrowse

FOR i := 1 TO Len(GetList)
  aGetListItem := GetList[i]
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_PARENT])) == 'B'
    oParent := Eval(bBlock) // get parent
  ENDIF
  IF aGetListItem[nGETLIST_TYPE] == GETLIST_BROWSE
    oHtml := DC_HtmlBrowse():new(oParent,aGetListItem)
  ELSEIF aGetListItem[nGETLIST_TYPE] == GETLIST_BROWSECOL
    oHtml := DC_HtmlColumn():new(oParent,aGetListItem)
  ENDIF
  IF Empty(oMainHtml)
    oMainHtml := oHtml
  ENDIF
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_GROUP])) == 'B'
    Eval(bBlock,oHtml) // anchor object to variable
  ENDIF
NEXT
cHtml := oMainHtml:writeHtml()
MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

_DCHTML.PRG

See Also:

   DCREAD HTML
   dc_html()
   dc_readhtml()
   @ DCBROWSE
   dc_htmlcolumn()


dc_htmlcheckbox()

A class for creating a CHECKBOX in HTML

DC_HtmlCheckBox() is a class for creating HTML checkbox input elements. The :writeHtml() method returns the source code of the INPUT tag.

Syntax:

DC_HtmlCheckBox():new( [ <oParent> ], ;
                       <aGetListItem> ) -> self

Arguments:

<oParent> is the parent object.  It must be already initialized
and must be of the DC_Html*() class.

<aGetListItem> is the item of the GetList associated with
this class.

Notes:

Inherits from DC_Html().Parent object may be from any DC_Html*() class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], oForm, oHtml, oParent, cHtml, oMainHtml, ;
      aGetListItem, bBlock, oTable, lCheck1, lCheck2, lCheck3

DCFORM OBJECT oForm
DCTABLE OBJECT oTable PARENT oForm ROWS 3 COLUMNS 1
lCheck1 := .t.
lCheck2 := .f.
lCheck3 := .f.
@ 1,1 DCCHECKBOX lCheck1 PROMPT 'Check me first' PARENT oTable
@ 2,1 DCCHECKBOX lCheck2 PROMPT 'Check me second' PARENT oTable
@ 3,1 DCCHECKBOX lCheck3 PROMPT 'Check me third' PARENT oTable

FOR i := 1 TO Len(GetList)
  aGetListItem := GetList[i]
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_PARENT])) == 'B'
    oParent := Eval(bBlock) // get parent
  ENDIF
  IF aGetListItem[nGETLIST_TYPE] == GETLIST_HTMLFORM
    oHtml := DC_HtmlForm():new(oParent,aGetListItem)
  ELSEIF aGetListItem[nGETLIST_TYPE] == GETLIST_HTMLTABLE
    oHtml := DC_HtmlTable():new(oParent,aGetListItem)
  ELSEIF aGetListItem[nGETLIST_TYPE] == GETLIST_CHECKBOX
    oHtml := DC_HtmlCheckBox():new(oParent,aGetListItem)
  ENDIF
  IF Empty(oMainHtml)
    oMainHtml := oHtml
  ENDIF
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_GROUP])) == 'B'
    Eval(bBlock,oHtml) // anchor object to variable
  ENDIF
NEXT
cHtml := oMainHtml:writeHtml()
MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

_DCHTML.PRG

See Also:

   DCREAD HTML
   dc_html()
   dc_readhtml()
   @ DCCHECKBOX


dc_htmlcolumn()

A class for creating a BROWSE COLUMN in HTML

DC_HtmlColumn() is a class for creating HTML table columns. The :writeHtml() method returns the source code of the column tags and all of its child elements. <br><br>The parent of DC_HtmlColumn() objects must be of the DC_HtmlBrowse() class.

Syntax:

DC_HtmlColumn():new( [ <oParent> ], ;
                     <aGetListItem> ) -> self

Arguments:

<oParent> is the parent object.  It must be already initialized
and must be of the DC_HtmlBrowse() class.

<aGetListItem> is the item of the GetList associated with
this class.

Notes:

Inherits from DC_Html().Parent object must be from any DC_HtmlBrowse() class.

Examples:

/*
This is an example of an array browse
*/

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], oTable, oHtml, oParent, cHtml, oMainHtml, ;
      aGetListItem, bBlock, aDir := Directory()

@ 0,0 DCBROWSE oBrowse SIZE 4,10 DATA aDir

DCBROWSECOL ELEMENT 1 HEADER 'File Name' PARENT oBrowse
DCBROWSECOL ELEMENT 2 HEADER 'File Size' PARENT oBrowse
DCBROWSECOL ELEMENT 3 HEADER 'File Date' PARENT oBrowse
DCBROWSECOL ELEMENT 4 HEADER 'File Time' PARENT oBrowse

FOR i := 1 TO Len(GetList)
  aGetListItem := GetList[i]
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_PARENT])) == 'B'
    oParent := Eval(bBlock) // get parent
  ENDIF
  IF aGetListItem[nGETLIST_TYPE] == GETLIST_BROWSE
    oHtml := DC_HtmlBrowse():new(oParent,aGetListItem)
  ELSEIF aGetListItem[nGETLIST_TYPE] == GETLIST_BROWSECOL
    oHtml := DC_HtmlColumn():new(oParent,aGetListItem)
  ENDIF
  IF Empty(oMainHtml)
    oMainHtml := oHtml
  ENDIF
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_GROUP])) == 'B'
    Eval(bBlock,oHtml) // anchor object to variable
  ENDIF
NEXT
cHtml := oMainHtml:writeHtml()
MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

_DCHTML.PRG

See Also:

   DCREAD HTML
   dc_html()
   dc_readhtml()
   DCBROWSECOL
   dc_htmlbrowse()


dc_htmlcombobox()

A class for creating a COMBO BOX in HTML

DC_HtmlComboBox() is a class for creating HTML select input elements. The :writeHtml() method returns the source code of the SELECT and OPTIONS tags.

Syntax:

DC_HtmlComboBox():new( [ <oParent> ], ;
                       <aGetListItem> ) -> self

Arguments:

<oParent> is the parent object.  It must be already initialized
and must be of the DC_Html*() class.

<aGetListItem> is the item of the GetList associated with
this class.

Notes:

Inherits from DC_Html().Parent object may be from any DC_Html*() class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], oForm, oHtml, oParent, cHtml, oMainHtml, ;
      aGetListItem, bBlock, oTable, aList1, aList2, cVar1, cVar2

DCFORM OBJECT oForm
DCTABLE OBJECT oTable PARENT oForm ROWS 2 COLUMNS 1
cVar1 := Space(10)
cVar2 := Space(12)
aList1 := { 'Men','Women','Dogs','Cats','Mice','Geese','Turkeys' }
aList2 := { 'Democrat','Republican','HandyMan','Doctor','Plumber','Programmer' }

@ 1,1 DCSAY 'Pick a group' PARENT oTable
@ 1,1 DCCOMBOBOX cVar1 LIST aList1 PARENT oTable
@ 2,1 DCSAY 'Pick a profession' PARENT oTable
@ 2,1 DCCOMBOBOX cVar2 LIST aList2 PARENT oTable

FOR i := 1 TO Len(GetList)
  aGetListItem := GetList[i]
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_PARENT])) == 'B'
    oParent := Eval(bBlock) // get parent
  ENDIF
  IF aGetListItem[nGETLIST_TYPE] == GETLIST_HTMLFORM
    oHtml := DC_HtmlForm():new(oParent,aGetListItem)
  ELSEIF aGetListItem[nGETLIST_TYPE] == GETLIST_HTMLTABLE
    oHtml := DC_HtmlTable():new(oParent,aGetListItem)
  ELSEIF aGetListItem[nGETLIST_TYPE] == GETLIST_SAY
    oHtml := DC_HtmlSay():new(oParent,aGetListItem)
  ELSEIF aGetListItem[nGETLIST_TYPE] == GETLIST_COMBOBOX
    oHtml := DC_HtmlComboBox():new(oParent,aGetListItem)
  ENDIF
  IF Empty(oMainHtml)
    oMainHtml := oHtml
  ENDIF
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_GROUP])) == 'B'
    Eval(bBlock,oHtml) // anchor object to variable
  ENDIF
NEXT
cHtml := oMainHtml:writeHtml()
MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

_DCHTML.PRG

See Also:

   DCREAD HTML
   dc_html()
   dc_readhtml()
   @ DCCOMBOBOX


dc_htmlform()

A class for creating FORM tags in HTML

DC_HtmlForm() is a class for creating HTML form elements. The :writeHtml() method returns the source code of the FORM tag.<br><br>

Syntax:

DC_HtmlForm():new( [ <oParent> ], ;
                   <aGetListItem> ) -> self

Arguments:

<oParent> is the parent object.  It must be already initialized
and must be of the DC_Html*() class.

<aGetListItem> is the item of the GetList associated with
this class.

Notes:

Inherits from DC_Html().Child objects may be from any DC_Html*() class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], oForm, oHtml, oParent, cHtml, oMainHtml, ;
      aGetListItem, bBlock, oTable, cComment1, cComment2

DCFORM OBJECT oForm METHOD "POST" ;
  ACTION "http://donnay-software.com:8083"

DCTABLE OBJECT oTable PARENT oForm ROWS 2 COLUMNS 1 WIDTH '200'

cComment1 := 'This is memo 1'
cComment2 := 'This is memo 2'

@ 1,1 DCMULTILINE cComment1 PARENT oTable SIZE 30,10 NAME 'Memo1'
@ 2,1 DCMULTILINE cComment2 PARENT oTable SIZE 30,10 NAME 'Memo2'

FOR i := 1 TO Len(GetList)
  aGetListItem := GetList[i]
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_PARENT])) == 'B'
    oParent := Eval(bBlock) // get parent
  ENDIF
  IF aGetListItem[nGETLIST_TYPE] == GETLIST_HTMLFORM
    oHtml := DC_HtmlForm():new(oParent,aGetListItem)
  ELSEIF aGetListItem[nGETLIST_TYPE] == GETLIST_HTMLTABLE
    oHtml := DC_HtmlTable():new(oParent,aGetListItem)
  ELSEIF aGetListItem[nGETLIST_TYPE] == GETLIST_MLE
    oHtml := DC_HtmlMle():new(oParent,aGetListItem)
  ENDIF
  IF Empty(oMainHtml)
    oMainHtml := oHtml
  ENDIF
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_GROUP])) == 'B'
    Eval(bBlock,oHtml) // anchor object to variable
  ENDIF
NEXT
cHtml := oMainHtml:writeHtml()
MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

_DCHTML.PRG

See Also:

   DCREAD HTML
   dc_html()
   dc_readhtml()


dc_htmlframe()

A class for creating FRAME tags in HTML

DC_HtmlFrame() is a class for creating HTML frame elements. <br><br>The :writeHtml() method returns the source code of the FRAMESET tag.<br><br>

Syntax:

DC_HtmlFrame():new( [ <oParent> ], ;
                    <aGetListItem> ) -> self

Arguments:

<oParent> is the parent object.  It must be already initialized
and must be of the DC_Html*() class.

<aGetListItem> is the item of the GetList associated with
this class.

Notes:

Inherits from DC_Html().Parent objects must be from the DC_HtmlFrameSet() class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], oHtml, oParent, cHtml, oMainHtml, ;
      aGetListItem, bBlock, oFrameSet, aClass

DCFRAMESET OBJECT oFrameSet ;
      ROWS '60%,*'

DCFRAME ;
     PARENT  oFrameSet ;
     NAME 'donnay' ;
     SRC 'http://donnay-software.com'

DCFRAME ;
     PARENT oFrameSet ;
     FRAMEBORDER 0 ;
     NAME 'google' ;
     SRC 'http://www.google.com'

aClass := { { GETLIST_HTMLFRAMESET, {|o,a|DC_HtmlFrameSet():new(o,a)} }, ;
            { GETLIST_HTMLFRAME   , {|o,a|DC_HtmlFrame():new(o,a)} } }

FOR i := 1 TO Len(GetList)
  oParent := nil
  aGetListItem := GetList[i]
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_PARENT])) == 'B'
    oParent := Eval(bBlock) // get parent
  ENDIF
  IF (nIndex := AScan( aClass, {|a|a[1]==aGetListItem[nGETLIST_TYPE]} )) > 0
    oHtml := Eval(aClass[nIndex,2],oParent,aGetListItem)
  ENDIF
  IF Empty(oMainHtml)
    oMainHtml := oHtml
  ENDIF
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_GROUP])) == 'B'
    Eval(bBlock,oHtml) // anchor object to variable
  ENDIF
NEXT
cHtml := oMainHtml:writeHtml()
MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

_DCHTML.PRG

See Also:

   DCREAD HTML
   dc_html()
   dc_readhtml()
   DCFRAME


dc_htmlframeset()

A class for creating FRAMESET tags in HTML

DC_HtmlFrameSet() is a class for creating HTML frameset elements. <br><br>The :writeHtml() method returns the source code of the FRAMESET tag.<br><br>

Syntax:

DC_HtmlFrameSet():new( [ <oParent> ], ;
                       <aGetListItem> ) -> self

Arguments:

<oParent> is the parent object.  It must be already initialized
and must be of the DC_Html*() class.

<aGetListItem> is the item of the GetList associated with
this class.

Notes:

Inherits from DC_Html().Child objects must be from the DC_HtmlFrame() class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], oHtml, oParent, cHtml, oMainHtml, ;
      aGetListItem, bBlock, oFrameSet, aClass

DCFRAMESET OBJECT oFrameSet ;
      ROWS '60%,*'

DCFRAME ;
     PARENT  oFrameSet ;
     NAME 'donnay' ;
     SRC 'http://donnay-software.com'

DCFRAME ;
     PARENT oFrameSet ;
     FRAMEBORDER 0 ;
     NAME 'google' ;
     SRC 'http://www.google.com'

aClass := { { GETLIST_HTMLFRAMESET, {|o,a|DC_HtmlFrameSet():new(o,a)} }, ;
            { GETLIST_HTMLFRAME   , {|o,a|DC_HtmlFrame():new(o,a)} } }

FOR i := 1 TO Len(GetList)
  oParent := nil
  aGetListItem := GetList[i]
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_PARENT])) == 'B'
    oParent := Eval(bBlock) // get parent
  ENDIF
  IF (nIndex := AScan( aClass, {|a|a[1]==aGetListItem[nGETLIST_TYPE]} )) > 0
    oHtml := Eval(aClass[nIndex,2],oParent,aGetListItem)
  ENDIF
  IF Empty(oMainHtml)
    oMainHtml := oHtml
  ENDIF
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_GROUP])) == 'B'
    Eval(bBlock,oHtml) // anchor object to variable
  ENDIF
NEXT
cHtml := oMainHtml:writeHtml()
MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

_DCHTML.PRG

See Also:

   DCREAD HTML
   dc_html()
   dc_readhtml()
   DCFRAMESET


dc_htmlget()

A class for creating a GET in HTML

DC_HtmlGet() is a class for creating HTML text type input elements. The :writeHtml() method returns the source code of the INPUT tag.

Syntax:

DC_HtmlGet():new( [ <oParent> ], ;
                  <aGetListItem> ) -> self

Arguments:

<oParent> is the parent object.  It must be already initialized
and must be of the DC_Html*() class.

<aGetListItem> is the item of the GetList associated with
this class.

Notes:

Inherits from DC_Html().Parent object may be from any DC_Html*() class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], oForm, oHtml, oParent, cHtml, oMainHtml, ;
      aGetListItem, bBlock, oTable, cUserId, cPassword

DCFORM OBJECT oForm
DCTABLE OBJECT oTable PARENT oForm ROWS 2 COLUMNS 2 WIDTH '200'

cUserId := Space(10)
cPassword := Space(10)

@ 1,1 DCSAY 'User ID' PARENT oTable
@ 1,2 DCGET cUserId PARENT oTable NAME 'App.User'
@ 2,1 DCSAY 'Password' PARENT oTable
@ 2,2 DCGET cUserId PARENT oTable NAME 'App.Password' PASSWORD

FOR i := 1 TO Len(GetList)
  aGetListItem := GetList[i]
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_PARENT])) == 'B'
    oParent := Eval(bBlock) // get parent
  ENDIF
  IF aGetListItem[nGETLIST_TYPE] == GETLIST_HTMLFORM
    oHtml := DC_HtmlForm():new(oParent,aGetListItem)
  ELSEIF aGetListItem[nGETLIST_TYPE] == GETLIST_HTMLTABLE
    oHtml := DC_HtmlTable():new(oParent,aGetListItem)
  ELSEIF aGetListItem[nGETLIST_TYPE] == GETLIST_SAY
    oHtml := DC_HtmlSay():new(oParent,aGetListItem)
  ELSEIF aGetListItem[nGETLIST_TYPE] == GETLIST_GET
    oHtml := DC_HtmlGet():new(oParent,aGetListItem)
  ENDIF
  IF Empty(oMainHtml)
    oMainHtml := oHtml
  ENDIF
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_GROUP])) == 'B'
    Eval(bBlock,oHtml) // anchor object to variable
  ENDIF
NEXT
cHtml := oMainHtml:writeHtml()
MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

_DCHTML.PRG

See Also:

   DCREAD HTML
   dc_html()
   dc_readhtml()
   @ DCGET


dc_htmlhyperlink()

A class for creating HYPERLINK tags in HTML

DC_HtmlHyperlink() is a class for creating HTML href elements for hyperlinks. The :writeHtml() method returns the source code of the <A> tag.

Syntax:

DC_HtmlHyperLink():new( [ <oParent> ], ;
                        <aGetListItem> ) -> self

Arguments:

<oParent> is the parent object.  It must be already initialized
and must be of the DC_Html*() class.

<aGetListItem> is the item of the GetList associated with
this class.

Notes:

Inherits from DC_Html().Parent object may be from any DC_Html*() class.Child objects may be from any DC_Html*() class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], oHtml, oParent, cHtml, oMainHtml, ;
      aGetListItem, bBlock, oLink, aClass

DCHYPERLINK HREF "http://donnay-software.com" ;
      OBJECT oLink

DCIMAGE SRC "http://donnay-software.com/graphics/donnay-logo.jpg" ;
      ALT 'Donnay Logo' PARENT oTable ;
      HEIGHT 100 ;
      PARENT oLink

aClass := { { GETLIST_HTMLLINK , {|o,a|DC_HtmlHyperLink():new(o,a)} }, ;
            { GETLIST_HTMLIMAGE, {|o,a|DC_HtmlImage():new(o,a)} } }

FOR i := 1 TO Len(GetList)
  oParent := nil
  aGetListItem := GetList[i]
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_PARENT])) == 'B'
    oParent := Eval(bBlock) // get parent
  ENDIF
  IF (nIndex := AScan( aClass, {|a|a[1]==aGetListItem[nGETLIST_TYPE]} )) > 0
    oHtml := Eval(aClass[nIndex,2],oParent,aGetListItem)
  ENDIF
  IF Empty(oMainHtml)
    oMainHtml := oHtml
  ENDIF
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_GROUP])) == 'B'
    Eval(bBlock,oHtml) // anchor object to variable
  ENDIF
NEXT
cHtml := oMainHtml:writeHtml()
MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

_DCHTML.PRG

See Also:

   DCREAD HTML
   dc_html()
   dc_readhtml()


dc_htmlimage()

A class for creating IMAGE tags in HTML

DC_HtmlImage() is a class for creating HTML image elements. The :writeHtml() method returns the source code of the IMG tag.

Syntax:

DC_HtmlImage():new( [ <oParent> ], ;
                    <aGetListItem> ) -> self

Arguments:

<oParent> is the parent object.  It must be already initialized
and must be of the DC_Html*() class.

<aGetListItem> is the item of the GetList associated with
this class.

Notes:

Inherits from DC_Html().Parent object may be from any DC_Html*() class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], oHtml, oParent, cHtml, oMainHtml, ;
      aGetListItem, bBlock, aClass

DCTABLE OBJECT oTable ;
       ROWS 1 COLUMNS 2 BORDER 1

@ 1,1 DCIMAGE SRC "http://donnay-software.com\graphics\donnay-logo.jpg" ;
        ALT 'Donnay Logo' PARENT oTable ;
        HEIGHT 100

@ 1,2 DCIMAGE SRC "http://donnay-software.com\graphics\xb2net.gif" ;
        ALT 'XB2.NET Logo' PARENT oTable ;
      VSPACE 20 ;
      HSPACE 20

aClass := { { GETLIST_HTMLTABLE   , {|o,a|DC_HtmlTable():new(o,a)} }, ;
            { GETLIST_HTMLIMAGE   , {|o,a|DC_HtmlImage():new(o,a)} } }

FOR i := 1 TO Len(GetList)
  oParent := nil
  aGetListItem := GetList[i]
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_PARENT])) == 'B'
    oParent := Eval(bBlock) // get parent
  ENDIF
  IF (nIndex := AScan( aClass, {|a|a[1]==aGetListItem[nGETLIST_TYPE]} )) > 0
    oHtml := Eval(aClass[nIndex,2],oParent,aGetListItem)
  ENDIF
  IF Empty(oMainHtml)
    oMainHtml := oHtml
  ENDIF
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_GROUP])) == 'B'
    Eval(bBlock,oHtml) // anchor object to variable
  ENDIF
NEXT
cHtml := oMainHtml:writeHtml()
MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

_DCHTML.PRG

See Also:

   DCREAD HTML
   dc_html()
   dc_readhtml()
   DCIMAGE


dc_htmlinput()

A class for creating an HTML input tag

DC_HtmlInput() is a class for creating different types of input elements to be used within a form.<br><br>The :writeHtml() method returns the source code of the IMG tag.

Syntax:

DC_HtmlInput():new( [ <oParent> ], ;
                    <aGetListItem> ) -> self

Arguments:

<oParent> is the parent object.  It must be already initialized
and must be of the DC_Html*() class.

<aGetListItem> is the item of the GetList associated with
this class.

Notes:

Inherits from DC_Html().Parent object may be from any DC_Html*() class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], oHtml, oParent, oTable, cHtml, oMainHtml, ;
      aGetListItem, bBlock, aClass, aListItems, cUserId, cPassword, ;
      lCheck, oForm

cUserId := Space(10)
cPassword := ''
lCheck := .t.
aListItems := { 'Men','Women','Dogs','Cats','Mice','Turkeys' }

DCFORM OBJECT oForm

DCTABLE OBJECT oTable ROWS 10 COLUMNS 2 BORDER 1 PARENT oForm

@ 1,1 DCSAY 'User ID' PARENT oTable
@ 1,2 DCINPUT VALUE cUserId NAME 'Input.Type.Text' ;
      PARENT oTable MAXLENGTH 10

@ 2,1 DCSAY 'Password' PARENT oTable
@ 2,2 DCINPUT TYPE "password" VALUE cPassword ;
      NAME 'Input.Type.PassWord' PARENT oTable MAXLENGTH 10

@ 3,1 DCSAY 'CheckBox' PARENT oTable
@ 3,2 DCINPUT TYPE "checkbox" NAME 'Input.Type.CheckBox' ;
      VALUE lCheck CHECKED PARENT oTable

@ 4,1 DCSAY 'Radio Buttons' PARENT oTable
@ 4,2 DCINPUT TYPE "radio" VALUE 'M' NAME 'Input.Type.RadioButton' ;
      PARENT oTable POST 'Mint<br>'
@ 4,2 DCINPUT TYPE "radio" VALUE 'E' NAME 'Input.Type.RadioButton' ;
      PARENT oTable POST 'Excellent<br>'
@ 4,2 DCINPUT TYPE "radio" VALUE 'G' NAME 'Input.Type.RadioButton' ;
      CHECKED PARENT oTable POST 'Good<br>'
@ 4,2 DCINPUT TYPE "radio" VALUE 'F' NAME 'Input.Type.RadioButton' ;
      PARENT oTable POST 'Fair<br>'
@ 4,2 DCINPUT TYPE "radio" VALUE 'P' NAME 'Input.Type.RadioButton' ;
      PARENT oTable POST 'Poor<br>'

@ 5,1 DCSAY 'Submit Button' PARENT oTable
@ 5,2 DCINPUT TYPE "submit" VALUE 'Hit Me!' ;
      NAME 'Input.Type.Submit' PARENT oTable

@ 6,1 DCSAY 'Reset Button' PARENT oTable
@ 6,2 DCINPUT TYPE "reset" VALUE 'Reset Form!' ;
      NAME 'Input.Type.Reset' PARENT oTable

@ 7,1 DCSAY 'Image' PARENT oTable
@ 7,2 DCINPUT TYPE "image" SRC '\exp18\images\express2.gif' ;
      NAME 'Input.Type.Image' PARENT oTable

@ 8,1 DCSAY 'ComboBox' PARENT oTable
@ 8,2 DCINPUT TYPE "select" ;
      LIST aListItems ;
      NAME 'Input.Type.Select' PARENT oTable

@ 9,1 DCSAY 'File' PARENT oTable
@ 9,2 DCINPUT TYPE "file" ;
      SIZE 40 ;
      MAXLENGTH 100 ;
      NAME 'Input.Type.File' PARENT oTable

@10,1 DCSAY 'Read Me' PARENT oTable
@10,2 DCINPUT ;
         TYPE DCHTML_INPUT_TEXTAREA ;
         WIDTH 60 HEIGHT 20 ;
         NAME 'Input.Type.TextArea' ;
         VALUE {||MemoRead('\exp18\samples\html\readme.txt')} ;
         PARENT oTable

aClass := { { GETLIST_HTMLINPUT, {|o,a|DC_HtmlInput():new(o,a)} }, ;
            { GETLIST_HTMLTABLE, {|o,a|DC_HtmlTable():new(o,a)} }, ;
            { GETLIST_HTMLFORM,  {|o,a|DC_HtmlForm():new(o,a)} }, ;
            { GETLIST_SAY      , {|o,a|DC_HtmlSay():new(o,a)} } }

FOR i := 1 TO Len(GetList)
  oParent := nil
  aGetListItem := GetList[i]
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_PARENT])) == 'B'
    oParent := Eval(bBlock) // get parent
  ENDIF
  IF (nIndex := AScan( aClass, {|a|a[1]==aGetListItem[nGETLIST_TYPE]} )) > 0
    oHtml := Eval(aClass[nIndex,2],oParent,aGetListItem)
  ENDIF
  IF Empty(oMainHtml)
    oMainHtml := oHtml
  ENDIF
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_GROUP])) == 'B'
    Eval(bBlock,oHtml) // anchor object to variable
  ENDIF
NEXT
cHtml := oMainHtml:writeHtml()
MemoWrit('TEST.HTM',cHtml)
RETURN cHtml

Files:

_DCHTML.PRG

See Also:

   DCREAD HTML


dc_htmllist()

A class for creating a LIST in HTML

DC_HtmlList() is a class for creating HTML list elements. The :writeHtml() method returns the source code of the UL, OL, DIR, MENU, DL and LI tags.

Syntax:

DC_HtmlList():new( [ <oParent> ], ;
                   <aGetListItem> ) -> self

Arguments:

<oParent> is the parent object.  It must be already initialized
and must be of the DC_Html*() class.

<aGetListItem> is the item of the GetList associated with
this class.

Notes:

Inherits from DC_Html().Parent object may be from any DC_Html*() class.Child objects must be of the DC_HtmlListItem() class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], oHtml, oParent, oTable, cHtml, oMainHtml, ;
      aGetListItem, bBlock, aClass, oList1, oList2, aListItems

aListItems := { 'Men','Women','Dogs','Cats','Mice','Turkeys' }

DCTABLE OBJECT oTable ROWS 1 COLUMNS 2

@ 1, 1 DCLIST OBJECT oList1 ;
     TYPE 'ol' ;
     ITEMLIST aListItems ;
     ITEMTYPE 'i' ;
     PARENT oTable

@ 1, 2 DCLIST OBJECT oList2 ;
     TYPE 'ul' ;
     PARENT oTable

FOR i := 1 TO Len(aListItems)
  DCLISTITEM aListItems[i] ;
  PARENT oList2 ;
  TYPE 'circle'
NEXT

aClass := { { GETLIST_HTMLLIST    , {|o,a|DC_HtmlList():new(o,a)} }, ;
            { GETLIST_HTMLLISTITEM, {|o,a|DC_HtmlListItem():new(o,a)} }, ;
            { GETLIST_HTMLTABLE   , {|o,a|DC_HtmlTable():new(o,a)} } }

FOR i := 1 TO Len(GetList)
  oParent := nil
  aGetListItem := GetList[i]
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_PARENT])) == 'B'
    oParent := Eval(bBlock) // get parent
  ENDIF
  IF (nIndex := AScan( aClass, {|a|a[1]==aGetListItem[nGETLIST_TYPE]} )) > 0
    oHtml := Eval(aClass[nIndex,2],oParent,aGetListItem)
  ENDIF
  IF Empty(oMainHtml)
    oMainHtml := oHtml
  ENDIF
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_GROUP])) == 'B'
    Eval(bBlock,oHtml) // anchor object to variable
  ENDIF
NEXT
cHtml := oMainHtml:writeHtml()
MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

_DCHTML.PRG

See Also:

   DCREAD HTML
   dc_html()
   dc_readhtml()


dc_htmllistitem()

A class for creating LIST ITEMS in HTML

DC_HtmlListItem() is a class for creating HTML list item elements. <br><br>The :writeHtml() method returns the source code of the LI tag.

Syntax:

DC_HtmlListItem():new( [ <oParent> ], ;
                       <aGetListItem> ) -> self

Arguments:

<oParent> is the parent object.  It must be already initialized
and must be of the DC_Html*() class.

<aGetListItem> is the item of the GetList associated with
this class.

Notes:

Inherits from DC_Html().Parent object must be of the DC_HtmlList() class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], oHtml, oParent, oTable, cHtml, oMainHtml, ;
      aGetListItem, bBlock, aClass, oList1, oList2, aListItems

aListItems := { 'Men','Women','Dogs','Cats','Mice','Turkeys' }

DCTABLE OBJECT oTable ROWS 1 COLUMNS 2

@ 1, 1 DCLIST OBJECT oList1 ;
     TYPE 'ol' ;
     ITEMLIST aListItems ;
     ITEMTYPE 'i' ;
     PARENT oTable

@ 1, 2 DCLIST OBJECT oList2 ;
     TYPE 'ul' ;
     PARENT oTable

FOR i := 1 TO Len(aListItems)
  DCLISTITEM aListItems[i] ;
  PARENT oList2 ;
  TYPE 'circle'
NEXT

aClass := { { GETLIST_HTMLLIST    , {|o,a|DC_HtmlList():new(o,a)} }, ;
            { GETLIST_HTMLLISTITEM, {|o,a|DC_HtmlListItem():new(o,a)} }, ;
            { GETLIST_HTMLTABLE   , {|o,a|DC_HtmlTable():new(o,a)} } }

FOR i := 1 TO Len(GetList)
  oParent := nil
  aGetListItem := GetList[i]
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_PARENT])) == 'B'
    oParent := Eval(bBlock) // get parent
  ENDIF
  IF (nIndex := AScan( aClass, {|a|a[1]==aGetListItem[nGETLIST_TYPE]} )) > 0
    oHtml := Eval(aClass[nIndex,2],oParent,aGetListItem)
  ENDIF
  IF Empty(oMainHtml)
    oMainHtml := oHtml
  ENDIF
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_GROUP])) == 'B'
    Eval(bBlock,oHtml) // anchor object to variable
  ENDIF
NEXT
cHtml := oMainHtml:writeHtml()
MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

_DCHTML.PRG

See Also:

   DCREAD HTML
   dc_html()
   dc_readhtml()


dc_htmlmain()

A class for creating the main HTML document

DC_HtmlMain() is a class for creating the beginning tags in an HTML document.<br><br>The :writeHtml() method returns the source code of the IMG tag.

Syntax:

DC_HtmlMain():new( [ <oParent> ], ;
                   <aGetListItem> ) -> self

Arguments:

<oParent> is the parent object.  It must be already initialized
and must be of the DC_Html*() class.

<aGetListItem> is the item of the GetList associated with
this class.

Notes:

Inherits from DC_Html().Child objects may be from any DC_Html*() class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], oMain, oHtml, oParent, cHtml, oMainHtml, ;
      aGetListItem, bBlock, aClass, oBody

DCHTMLMAIN OBJECT oMain

DCHTMLBODY OBJECT oBody ;
     BACKGROUND "http://donnay-software.com/graphics/expback1.gif" ;
     STYLE "\exp18\html\default.css" ;
     PARENT oMain

DCHTML TEXT MemoRead('\exp18\readme.txt') ;
     STYLE 'PRE' ;
     PARENT oBody

aClass := { { GETLIST_HTMLMAIN, {|o,a|DC_HtmlMain():new(o,a)} }, ;
            { GETLIST_HTMLBODY, {|o,a|DC_HtmlBody():new(o,a)} }, ;
            { GETLIST_HTML    , {|o,a|DC_Html():new(o,a)} } }

FOR i := 1 TO Len(GetList)
  oParent := nil
  aGetListItem := GetList[i]
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_PARENT])) == 'B'
    oParent := Eval(bBlock) // get parent
  ENDIF
  IF (nIndex := AScan( aClass, {|a|a[1]==aGetListItem[nGETLIST_TYPE]} )) > 0
    oHtml := Eval(aClass[nIndex,2],oParent,aGetListItem)
  ENDIF
  IF Empty(oMainHtml)
    oMainHtml := oHtml
  ENDIF
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_GROUP])) == 'B'
    Eval(bBlock,oHtml) // anchor object to variable
  ENDIF
NEXT
cHtml := oMainHtml:writeHtml()
MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

_DCHTML.PRG

See Also:

   DCREAD HTML
   DCHTMLMAIN


dc_htmlmle()

A class for creating a MEMO window in HTML

DC_HtmlMle() is a class for creating HTML textarea elements. The :writeHtml() method returns the source code of the TEXTAREA tag.

Syntax:

DC_HtmlMle():new( [ <oParent> ], ;
                   <aGetListItem> ) -> self

Arguments:

<oParent> is the parent object.  It must be already initialized
and must be of the DC_Html*() class.

<aGetListItem> is the item of the GetList associated with
this class.

Notes:

Inherits from DC_Html().Parent object may be from any DC_Html*() class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], oForm, oHtml, oParent, cHtml, oMainHtml, ;
      aGetListItem, bBlock, oTable, cComment1, cComment2

DCFORM OBJECT oForm
DCTABLE OBJECT oTable PARENT oForm ROWS 2 COLUMNS 1 WIDTH '200'

cComment1 := 'This is memo 1'
cComment2 := 'This is memo 2'

@ 1,1 DCMULTILINE cComment1 PARENT oTable SIZE 30,10 NAME 'Memo1'
@ 2,1 DCMULTILINE cComment2 PARENT oTable SIZE 30,10 NAME 'Memo2'

FOR i := 1 TO Len(GetList)
  aGetListItem := GetList[i]
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_PARENT])) == 'B'
    oParent := Eval(bBlock) // get parent
  ENDIF
  IF aGetListItem[nGETLIST_TYPE] == GETLIST_HTMLFORM
    oHtml := DC_HtmlForm():new(oParent,aGetListItem)
  ELSEIF aGetListItem[nGETLIST_TYPE] == GETLIST_HTMLTABLE
    oHtml := DC_HtmlTable():new(oParent,aGetListItem)
  ELSEIF aGetListItem[nGETLIST_TYPE] == GETLIST_MLE
    oHtml := DC_HtmlMle():new(oParent,aGetListItem)
  ENDIF
  IF Empty(oMainHtml)
    oMainHtml := oHtml
  ENDIF
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_GROUP])) == 'B'
    Eval(bBlock,oHtml) // anchor object to variable
  ENDIF
NEXT
cHtml := oMainHtml:writeHtml()
MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

_DCHTML.PRG

See Also:

   DCREAD HTML
   dc_html()
   dc_readhtml()
   @ DCMULTILINE


dc_htmlradiobutton()

A class for creating a RADIO BUTTON in HTML

DC_HtmlRadioButton() is a class for creating HTML radio button input elements. The :writeHtml() method returns the source code of the INPUT tag.

Syntax:

DC_HtmlRadioButton():new( [ <oParent> ], ;
                          <aGetListItem> ) -> self

Arguments:

<oParent> is the parent object.  It must be already initialized
and must be of the DC_Html*() class.

<aGetListItem> is the item of the GetList associated with
this class.

Notes:

Inherits from DC_Html().Parent object may be from any DC_Html*() class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], oForm, oHtml, oParent, cHtml, oMainHtml, ;
      aGetListItem, bBlock, oTable, cProfession := 'Doctor'

aProfession := { 'Democrat','Republican','HandyMan','Doctor', ;
                 'Plumber','Programmer' }

DCFORM OBJECT oForm
DCTABLE OBJECT oTable PARENT oForm ROWS Len(aProfession) COLUMNS 1

FOR i := 1 TO Len(aProfession)
  @ i,1 DCRADIOBUTTON cProfession VALUE aProfession[i] ;
        PROMPT aProfession[i] PARENT oTable
NEXT

FOR i := 1 TO Len(GetList)
  aGetListItem := GetList[i]
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_PARENT])) == 'B'
    oParent := Eval(bBlock) // get parent
  ENDIF
  IF aGetListItem[nGETLIST_TYPE] == GETLIST_HTMLFORM
    oHtml := DC_HtmlForm():new(oParent,aGetListItem)
  ELSEIF aGetListItem[nGETLIST_TYPE] == GETLIST_HTMLTABLE
    oHtml := DC_HtmlTable():new(oParent,aGetListItem)
  ELSEIF aGetListItem[nGETLIST_TYPE] == GETLIST_RADIOBUTTON
    oHtml := DC_HtmlRadioButton():new(oParent,aGetListItem)
  ENDIF
  IF Empty(oMainHtml)
    oMainHtml := oHtml
  ENDIF
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_GROUP])) == 'B'
    Eval(bBlock,oHtml) // anchor object to variable
  ENDIF
NEXT
cHtml := oMainHtml:writeHtml()
MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

_DCHTML.PRG

See Also:

   DCREAD HTML
   dc_html()
   dc_readhtml()
   @ DCRADIOBUTTON


dc_htmlsay()

A class for creating a SAY in HTML

DC_HtmlSay() is a class for creating HTML text. The :writeHtml() method returns the source code.

Syntax:

DC_HtmlSay():new( [ <oParent> ], ;
                  <aGetListItem> ) -> self

Arguments:

<oParent> is the parent object.  It must be already initialized
and must be of the DC_Html*() class.

<aGetListItem> is the item of the GetList associated with
this class.

Notes:

Inherits from DC_Html().Parent object may be from any DC_Html*() class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], oForm, oHtml, oParent, cHtml, oMainHtml, ;
      aGetListItem, bBlock, oTable, cProfession := 'Doctor'

aProfession := { 'Democrat','Republican','HandyMan','Doctor','Plumber','Programmer' }

DCFORM OBJECT oForm
DCTABLE OBJECT oTable PARENT oForm ROWS Len(aProfession) COLUMNS 1

FOR i := 1 TO Len(aProfession)
  @ i,1 DCSAY aProfession[i] PARENT oTable
NEXT

FOR i := 1 TO Len(GetList)
  aGetListItem := GetList[i]
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_PARENT])) == 'B'
    oParent := Eval(bBlock) // get parent
  ENDIF
  IF aGetListItem[nGETLIST_TYPE] == GETLIST_HTMLFORM
    oHtml := DC_HtmlForm():new(oParent,aGetListItem)
  ELSEIF aGetListItem[nGETLIST_TYPE] == GETLIST_HTMLTABLE
    oHtml := DC_HtmlTable():new(oParent,aGetListItem)
  ELSEIF aGetListItem[nGETLIST_TYPE] == GETLIST_SAY
    oHtml := DC_HtmlSay():new(oParent,aGetListItem)
  ENDIF
  IF Empty(oMainHtml)
    oMainHtml := oHtml
  ENDIF
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_GROUP])) == 'B'
    Eval(bBlock,oHtml) // anchor object to variable
  ENDIF
NEXT
cHtml := oMainHtml:writeHtml()
MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

_DCHTML.PRG

See Also:

   DCREAD HTML
   dc_html()
   dc_readhtml()
   @ DCSAY


dc_htmltabgroup()

A class for creating TABPAGES in HTML

DC_HtmlTabGroup() is a class for creating HTML tables that emulate GUI tab pages. The :writeHtml() method returns the source code of the table tag and all of its child elements.

Syntax:

DC_HtmlTabGroup():new( [ <oParent> ], ;
                       <aGetListItem> ) -> self

Arguments:

<oParent> is the parent object.  It must be already initialized
and must be of the DC_Html*() class.

<aGetListItem> is the item of the GetList associated with
this class.

Notes:

Inherits from DC_Html() and DC_HtmlTable().Parent object may be from any DC_Html*() class.Child objects may be from any DC_Html*() class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], oForm, oHtml, oParent, cHtml, oMainHtml, ;
      aGetListItem, bBlock, oTabGroup, oTabs, aTabCaptions, ;
      aMemos[4], aClass

DCFORM OBJECT oForm

DCTABGROUP ;
       WIDTH '400' ;
       OBJECT oTabGroup ;
       TABOBJECT oTabs ;
       PARENT oForm ;
       SELECT 2 ;
       COLOR GRA_CLR_WHITE ;
       SELECTEDCOLOR GRA_CLR_GREEN ;
       UNSELECTEDCOLOR GRA_CLR_PALEGRAY ;
       BORDER 0 ;
       CELLPADDING 0 ;
       CELLSPACING 0 ;
       TABS 4

aTabCaptions := {'Customer','Vendor','History','Misc'}

FOR i := 1 TO Len(aTabCaptions)

  DCSUBMIT ;
    TYPE DCHTML_BUTTONTYPE_SUBMIT ;
    CAPTION aTabCaptions[i] ;
    PARENT oTabs ;
    NAME 'App.Tab'  + Alltrim(Str(i))

  aMemos[i] := 'This is the ' + aTabCaptions[i] + ' Memo'
  @ 0,0 DCMULTILINE aMemos[i] SIZE 60,10 ;
    PARENT oTabGroup

NEXT

aClass := { { GETLIST_HTMLFORM    , {|o,a|DC_HtmlForm():new(o,a)} }, ;
            { GETLIST_HTMLTABGROUP, {|o,a|DC_HtmlTabGroup():new(o,a)} }, ;
            { GETLIST_MLE         , {|o,a|DC_HtmlMle():new(o,a)} }, ;
            { GETLIST_HTMLSUBMIT  , {|o,a|DC_HtmlSubmit():new(o,a)} } }

FOR i := 1 TO Len(GetList)
  oParent := nil
  aGetListItem := GetList[i]
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_PARENT])) == 'B'
    oParent := Eval(bBlock) // get parent
  ENDIF
  IF (nIndex := AScan( aClass, {|a|a[1]==aGetListItem[nGETLIST_TYPE]} )) > 0
    oHtml := Eval(aClass[nIndex,2],oParent,aGetListItem)
  ENDIF
  IF Empty(oMainHtml)
    oMainHtml := oHtml
  ENDIF
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_GROUP])) == 'B'
    Eval(bBlock,oHtml) // anchor object to variable
  ENDIF
NEXT
cHtml := oMainHtml:writeHtml()
MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

_DCHTML.PRG

See Also:

   DCREAD HTML
   dc_html()
   dc_readhtml()
   DCTABGROUP


dc_htmltable()

A class for creating a TABLE in HTML

DC_HtmlTable() is a class for creating HTML tables. The :writeHtml() method returns the source code of the table tag and all of its child elements.<br><br>

Syntax:

DC_HtmlTable():new( [ <oParent> ], ;
                    <aGetListItem> ) -> self

Arguments:

<oParent> is the parent object.  It must be already initialized
and must be of the DC_Html*() class.

<aGetListItem> is the item of the GetList associated with
this class.

Notes:

Inherits from DC_Html().Parent object may be from any DC_Html*() class.Child objects may be from any DC_Html*() class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Main()

LOCAL i, GetList[0], oTable, oHtml, oParent, cHtml, oMainHtml, ;
      aGetListItem, bBlock

DCTABLE OBJECT oTable ROWS 5 COLS 4
@ 2,3 DCHTML TEXT 'This is some text' PARENT oTable
@ 4,4 DCHTML TEXT 'This is some more text' PARENT oTable

FOR i := 1 TO Len(GetList)
  aGetListItem := GetList[i]
  IF Valtype(bBlock := aGetListItem[bGETLIST_PARENT]) == 'B'
    oParent := Eval(bBlock) // get parent
  ENDIF
  IF aGetListItem[nGETLIST_TYPE] == GETLIST_HTML
    oHtml := DC_Html():new(oParent,aGetListItem)
  ELSEIF aGetListItem[nGETLIST_TYPE] == GETLIST_HTMLTABLE
    oHtml := DC_HtmlTable():new(oParent,aGetListItem)
  ENDIF
  IF Empty(oMainHtml)
    oMainHtml := oHtml
  ENDIF
  IF Valtype(bBlock := aGetListItem[bGETLIST_GROUP]) == 'B'
    Eval(bBlock,oHtml) // anchor object to variable
  ENDIF
NEXT

cHtml := oMainHtml:writeHtml()
MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

_DCHTML.PRG

See Also:

   DCREAD HTML
   dc_html()
   dc_readhtml()


dc_htmlvars()

A class for managing HIDDEN variables in HTML

DC_HtmlVars() is a class for managing hidden variables in HTML applications. <br><br>The :writeHtml() method returns the source code of the element tags.<br><br>Variables are received from an HTML form in GET or POST HTTP requests. The Alaska Software WAA and Boris Borzic's XB2.NET handle these variables in a similar manner and make them available as a 2-dimensional array which each sub-array containing the name and the value. Many times it is desirable to replicate these variable names and their values in the HTML response. These are referred to as "hidden" variables and are inserted into the HTML source as <INPUT type=hidden> elements. The is the way HTML applications manage the state of an application without requiring the use of cookies or other state management techniques such as static variables. By replicating hidden variables, the application will always work and will not fail due to server connection timeouts or the user turning off "cookies".<br><br>

Syntax:

DC_HtmlVars():new( [ <oParent> ], ;
                   <aGetListItem> ) -> self

Arguments:

<oParent> is the parent object.  It must be already initialized
and must be of the DC_Html*() class.

<aGetListItem> is the item of the GetList associated with
this class.

Notes:

Inherits from DC_Html().Parent object must be from DC_HtmlForm() class.

Examples:

#include "dcdialog.ch"
#include "dchtml.ch"

FUNCTION Xtest()

LOCAL i, GetList[0], oHtml, oParent, cHtml, oMainHtml, ;
      aGetListItem, bBlock, aClass, aVars, oForm

aVars := { { 'App.Text.1', 'some text' }, ;
           { 'App.Text.2', 'more text' }, ;
           { 'App.Text.3', 'still more text' }, ;
           { 'App.Checkbox', 'on' }, ;
           { 'App.RadioButton', 'Mint' }, ;
           { 'App.Memo', 'lots of text' }, ;
           { 'App.RecordNumber', '12' }, ;
           { 'App.Database', 'CUSTOMER' }, ;
           { 'App.Account', '40055' } }

DCFORM OBJECT oForm

DCVARS ;
   PARENT oForm ;
   REPLICATE aVars ;
   EXCLUDE { 'App.Text.*','App.Memo' } ;
   INCLUDE { { 'App.Date', Date() }, ;
             { 'App.Time', Time() } }

aClass := { { GETLIST_HTMLVARS, {|o,a|DC_HtmlVars():new(o,a)} }, ;
            { GETLIST_HTMLFORM,  {|o,a|DC_HtmlForm():new(o,a)} } }

FOR i := 1 TO Len(GetList)
  oParent := nil
  aGetListItem := GetList[i]
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_PARENT])) == 'B'
    oParent := Eval(bBlock) // get parent
  ENDIF
  IF (nIndex := AScan( aClass, {|a|a[1]==aGetListItem[nGETLIST_TYPE]} )) > 0
    oHtml := Eval(aClass[nIndex,2],oParent,aGetListItem)
  ENDIF
  IF Empty(oMainHtml)
    oMainHtml := oHtml
  ENDIF
  IF Valtype(bBlock := DC_GetBlock(aGetListItem[bGETLIST_GROUP])) == 'B'
    Eval(bBlock,oHtml) // anchor object to variable
  ENDIF
NEXT
cHtml := oMainHtml:writeHtml()
MemoWrit('TEST.HTM',cHtml)

RETURN cHtml

Files:

_DCHTML.PRG

See Also:

   DCREAD HTML
   dc_html()
   dc_readhtml()
   DCVARS


dc_settimerevent()

Set a Timer Event

DC_SetTimerEvent() is used in place of SetTimerEvent() when more than one timer event is required to be running simultaneously.

Examples:

 oTimer := DC_SetTimerEvent:new( 100, {||UpdateTime()} )

 oTimer:destroy()  // stop timer

Files:

_DCFUNCT.PRG, DCLIPX.DLL


dc_xbppushbuttonxpconfig()

Configuration class for XP Style Pushbuttons

DC_XbpPushButtonXPConfig() is a class that is used to configure Pushbuttons created with the @ DCPUSHBUTTONXP or @ DCADDBUTTONXP commands.<br><br>This class is normally used to set a configuration for a group of buttons that all have the same basic properties, such as the same font, color, shape, etc.<br><br>The object created with this class is usually assigned to push buttons using the CONFIG clause of the @ DCPUSHBUTTONXP command.

Examples:

-- Example 1 --

oConfig1 := DC_XbpPushButtonXPConfig():new()
oConfig1:bitmapOffset := 5
oConfig1:fgColorMouse := COLOR_BLACK
oConfig1:bgColorMouse := COLOR_ORANGE
oConfig1:fgColor := COLOR_BLACK
oConfig1:bgColor := COLOR_BROWN
oConfig1:gradientStep := 10
oConfig1:gradientReverse := .t.
oConfig1:radius := 10
oConfig1:bgColorClick := GRA_CLR_YELLOW

@ 10,10 DCPUSHBUTTONXP CAPTION 'Test' SIZE 10,2 ;
  CONFIG oConfig1

Files:

_DCXBUTT.PRG, DCLIPX.DLL

See Also:

   @ dcpushbuttonxp
   dc_pushbuttonstyle()
   dc_xbppushbuttonxpdefault()
   dc_expressbuttonstyle()
   dc_popupbuttonstyle()


dc_xmlnode()

A class for managing XML nodes

DC_XmlNode() is a class that contains a set of methods for easily extracting the data from an XML object tree that was created with DC_Xml2ObjectTree().<br><br>

Examples:

#Pragma Library("DCXML.LIB")

FUNCTION XTest()

LOCAL oMainNode, oUserNode, aUserTags

SET DEFAULT TO ('..\..\data')
SET PATH TO ('..\..\data')

USE CUSTOMER

oMainNode := DC_XmlNode():new('DNN_BACKUP')

DO WHILE !CUSTOMER->(Eof())

  aUserTags := { ;
    {'BillName',    CUSTOMER->bill_name  }, ;
    {'BillStreet',  CUSTOMER->bill_strt  }, ;
    {'BillCity',    CUSTOMER->bill_name  }, ;
    {'BillZip',     CUSTOMER->bill_zip   }, ;
    {'BillState',   CUSTOMER->bill_state }, ;
    {'ShipName',    CUSTOMER->ship_name  }, ;
    {'ShipStreet',  CUSTOMER->ship_strt  }, ;
    {'ShipCity',    CUSTOMER->ship_name  }, ;
    {'ShipZip',     CUSTOMER->ship_zip   }, ;
    {'ShipState',   CUSTOMER->ship_state }, ;
    {'Phone',       CUSTOMER->phone      }, ;
    {'Fax',         CUSTOMER->fax        }, ;
    {'Contact',     CUSTOMER->contact    }, ;
    {'Email',       CUSTOMER->email      } }

  oUserNode := DC_XmlNode():New('USER',,,,aUserTags)
  oMainNode:addChild(oUserNode)

  CUSTOMER->(dbSkip())

ENDDO

oMainNode:writeXml('CUSTOMER.XML')
DCMSGBOX 'Done!'

RETURN nil

Files:

_DCXML.PRG, DCXML.DLL

See Also:

   dc_xml2objecttree()


MULTI-EDIT TEMPLATE

Template for Multi-Edit Professional Editor

EXPRESS.TPT is a template file for use with Multi-Edit,the programmer's editor. It contains templates for all eXPress++ commands and functions.<br><br> Just copy EXPRESS.TPT to your \MEW\CONFIG directory or whichever directory contains your Multi-Edit templates.<br><br> When Multi-Edit is configured for "Space-Bar Expansion" of a template, you can easily bring a template for any eXPress++ command into the text you are editing by typing the keyword for the command followed immediately by a SPACE.<br><br> For example, if you are not sure of the syntax of the DCTABPAGE command, simply type DCTABPAGE<space>. The following will be inserted into your text:<br><br> @ <nSRow>,<nSCol> DCTABPAGE <oGroup> ; [SIZE <nWidth>, <nHeight>] ; [TYPE <nType>] ; [TABHEIGHT <nTabH>] ; [PREOFFSET <nPre>] ; [POSTOFFSET <nPost>] ; [PARENT <oParent>] ; [GROUP <nGroup>] ; [CAPTION <cText>] ; [CARGO <xCargo>] ; [MESSAGE <cMsg>] ; [HELPCODE <cHelpCode>] ; [COLOR <ncColor> [,<ncDisabled>] ] ; [WHEN <bWhen>] ; [FONT <cFont>] ; [HIDE <bHide>] ; [VALID <bValid>] ; [<p: PIXEL>] ; [TOOLTIP <cToolTip>] ; [CURSOR <nCursor>] ; [RELATIVE <oRel>] ; [EVAL <bEval>] ; [DATALINK <bDataLink>] ; [ ID <cId> ]

Files:

EXPRESS.TPT


X2CLIP.EXE

Xbase to Clipper Interface for improved database performance

X2CLIP.EXE is a Clipper 5.2e program which is used to run database operations in the background. Some Xbase++ database operations, such as reindexing, appending, etc. are too slow, therefore a set of DC_XC*() functions is included in the DCLIPX.DLL library to improve database performance as much as 20 times.<br><br> The files needed to build X2CLIP.EXE are X2CLIP.PRG and X2CLIP.LNK. They are included in the \EXPRESS\SOURCE directory. When using the XC_PROGRAM operation in a parameters array passed to DC_XCCall(), the custom program must be written in Clipper, then compiled and linked into the X2CLIP.EXE program by adding it to the X2CLIP.LNK link script and re-linking the program with a Clipper linker. The custom program receives a single parameter which can be a multidimensional array of any type of information which is compatabile with both Xbase++ and Clipper. This array is stored in the XC_ARRAY_DATA element of the parameters array.<br><br> The X2CLIP.EXE program is called by the XBase++ program by a call to DC_XCOpen() which runs the X2CLIP.EXE program in the background. This program then runs a loop routine which waits for instructions from the Xbase++ program via calls to DC_XCCall().<br><br> The X2CLIP.EXE program is synchronized to the Xbase++ program through a system of data writes to a shared record in the X2CLIP.DBF file.

Notes:

The X2CLIP.EXE program is intended to be called only by the Xbase++ program using the RunShell() function launched in a separate thread. It is passed a handle number and a default directory. The handle number is the record number of X2CLIP.DBF to use to pass data back and forth from the Xbase++ program to the X2CLIP.EXE program. The default directory is the disk directory containing the X2CLIP.DBF file. If the file does not exist it will be created.

If the X2CLIP.EXE program fails to communicate with the Xbase++ program, it will stay in a loop indefinately or until the ESCAPE key is pressed.

Examples:

 MEM2XPP DISCLAIM.MEM

 MEM2XPP ALL

Files:

DC_XCOpen()


MEM2XPP.EXE

Convert Clipper .MEM files to Xbase++ .XPP files

MEM2XPP.EXE is an Xbase++ utility program that converts Clipper *.MEM files to XBase++ *.XPF files. Xbase++ is not compatible with Clipper .MEM files because they were designed for 16-bit systems and are insufficiently robust for the features of Xbase++. They must be converted to .XPF files for the REST FROM <memfile> command to work properly.<br><br> The original .MEM file is not altered in any way. A new file with the same prefix as the original file is created but with an extension of .XPF.<br><br> An additional file with the same prefix as the original files but with an extension on .TXT is also created. This is an ordinary text file that lists the memory variables and contents of the memory file.<br><br>

Syntax:

MEM2XPP <MemFileName> | ALL

Arguments:

<MemFileName> is the name of a Clipper .MEM file to convert.

If the ALL argument is used, then all files with the .MEM
extension will be converted to .XPF files with the same
prefix.

Examples:

 MEM2XPP DISCLAIM.MEM

 MEM2XPP ALL


OVERVIEW_ADSDBE

ADSDBE (Advantage Server) Functions

A complete set of client functions for the Advantage Database server exists in ACE32.DLL. This dynamic link library is included with the ADSDBE available from Alaska Software. The below set of ADS*() DLLFUNCTION wrappers and AX_*() wrappers provide a much simpler interface to this robust database library. The AX_*() wrappers are designed to be equivalent functions to those which exist in the Clipper 5.x client library. To use this library in Xbase++ applications, include the DCLIPX.LIB file in your link script or project file and make sure that DCLIPX.DLL exists in your workstations search path.<br><br> The complete set of AdsMg*() function wrappers is included with the ADSDBE product available from Alaska Software therefore they are not included here. To use AdsMg*() functions in your application, include the ADSMG.LIB in your link script or project file and make sure that ADSMG.DLL exists in your workstation search path.<br><br> The documentation for AX_() functions is included with the Clipper client kit available from Extended Systems. The documentation for ADS*() functions is included with the ACE32 SDK also available from Extended Systems, therefore the functions are not documented here. The ACE32 Client SDK is free. Just visit http://www.advantagedatabase.com *

Files:

_DCADS.PRG, DCLIPX.DLL


FUNCTIONS_AX

AX_*() Functions (Advantage Server)

The following list of AX_() functions are supported in DCLIPX.LIB / DCLIPX.DLL.<br><br>For complete documentation on how to use these functions, see the Clipper Client documentation available from Extended Systems. <pre> AX_AutoOpen() // not completed AX_BLOB2File() AX_CDXCheck() // not completed AX_ChooseOrgBagExt() AX_ClearOrder() AX_ClrScope() AX_Driver() AX_Error() AX_ExprEngine() // not supported in ACED32.DLL (always ON) AX_ExprError() // not completed AX_ExprValid() AX_File2BLOB() AX_FileOrder() // not completed AX_GetDrive() AX_GetLocks() AX_I_IndexName() // not completed AX_I_TagName() // not completed AX_IndexCount() AX_IndexFilt() AX_IndexName() AX_IndexType() // not completed AX_IsFlocked() AX_IsLocked() AX_IsReadOnly() AX_IsReIndex() // not completed AX_IsShared() AX_IsCustom() AX_IsDescend() AX_IsUnique() AX_KeyAdd() AX_KeyCount() AX_KeyDrop() AX_KeyNo() AX_KeysIncluded() AX_KeyVal() AX_KillTag() AX_Loaded() // extended functionality (see source) AX_MemoArrayStyle // not completed AX_RddCount() AX_RddInfo() AX_Rlock() AX_SeekLast() AX_SetMemoBlock() AX_SetRdd() AX_SetScope() AX_SetTag() AX_SetTagNo() AX_SetTagOrder() AX_SkipUnique() AX_TableName() AX_TagInfo() AX_TagName() AX_TagNo() AX_TagOrder() AX_Tags() AX_TPSCleanup() AX_Transaction() AX_Unlock() AX_UserLockID() // not completed </pre> The following list of AX_() functions are supported in the ADAC10.LIB / ADAC10.DLL files which are distributed with the ADSDBE available from Alaska Software.<br><br>For complete documentation on how to use these functions, see the Clipper Client documentation available from Extended Systems. <pre> AX_AXSLocking() AX_DbfDecrypt() AX_DbfEncrypt() AX_Decrypt() AX_Encrypt() AX_Error() AX_IDType() AX_RightsCheck() AX_SetPass() AX_TableType() </pre>

Files:

_DCADS.PRG, DCLIPX.DLL

See Also:

   FUNCTIONS_ADS_DRIVER


FUNCTIONS_ADS_TABLE

Ads_*() Table Functions (Advantage Server)

The following list of Ads*() table functions are supported in DCLIPX.LIB / DCLIPX.DLL:<br><br>For complete documentation on how to use these functions, see the ACE.HLP file available from Extended Systems. <pre> AdsAddCustomKey AdsAtBOF AdsAtEOF AdsCacheOpenTables AdsCacheRecords AdsCancelUpdate AdsClearAllScopes AdsClearAOF AdsClearFilter AdsClearRelation AdsClearScope AdsCloneTable AdsCloseAllIndexes AdsCloseAllTables AdsCloseIndex AdsCloseTable AdsContinue AdsConvertTable AdsCopyTable AdsCopyTableContents AdsCopyTableStructure AdsCreateIndex AdsCreateTable AdsCustomizeAOF AdsDecryptRecord AdsDecryptTable AdsDeleteCustomKey AdsDeleteIndex AdsDisableEncryption AdsEnableEncryption AdsEncryptRecord AdsEncryptTable AdsEvalAOF AdsEvalLogicalExpr AdsEvalNumericExpr AdsEvalStringExpr AdsEvalTestExpr AdsExtractKey AdsGetAllIndexes AdsGetAllLocks AdsGetAOF AdsGetAOFOptLevel AdsGetBookmark AdsGetFieldDecimals AdsGetFieldLength AdsGetFieldName AdsGetFieldNum AdsGetFieldOffset AdsGetFieldType AdsGetFilter AdsGetHandleLong AdsGetHandleType AdsGetIndexCondition AdsGetIndexExpr AdsGetIndexFilename AdsGetIndexHandle AdsGetIndexHandleByExpr AdsGetIndexHandleByOrder AdsGetIndexName AdsGetIndexOrderByHandle AdsGetKeyCount AdsGetKeyLength AdsGetKeyNum AdsGetKeyType AdsGetLastTableUpdate AdsGetNumFields AdsGetNumIndexes AdsGetNumLocks AdsGetRecordCount AdsGetRecordLength AdsGetRecordNum AdsGetRelKeyPos AdsGetScope AdsGetTableAlias AdsGetTableCharType AdsGetTableConnection AdsGetTableFilename AdsGetTableHandle AdsGetTableLockType AdsGetTableOpenOptions AdsGetTableRights AdsGetTableType AdsGotoBookmark AdsGotoBottom AdsGotoRecord AdsGotoTop AdsIsEncryptionEnabled AdsIsExprValid AdsIsFound AdsIsIndexCompound AdsIsIndexCustom AdsIsIndexDescending AdsIsIndexUnique AdsIsRecordDeleted AdsIsRecordEncrypted AdsIsRecordInAOF AdsIsRecordLocked AdsIsRecordVisible AdsIsTableEncrypted AdsIsTableLocked AdsLocate AdsLockRecord AdsLockTable AdsLookupKey AdsOpenIndex AdsOpenTable AdsPackTable AdsRefreshAOF AdsRefreshRecord AdsReindex AdsSeek AdsSeekLast AdsSetAOF AdsSetFilter AdsSetHandleLong AdsSetRelation AdsSetRelKeyPos AdsSetScope AdsSetScopedRelation AdsSkip AdsUnlockRecord AdsUnlockTable AdsVerifyPassword AdsZapTable </pre>

Files:

_DCADS.PRG, DCLIPX.DLL

See Also:

   FUNCTIONS_AX
   FUNCTIONS_ADS_DRIVER


FUNCTIONS_ADS_DRIVER

Ads_*() Driver Functions (Advantage Server)

The following list of Ads*() driver functions are supported in DCLIPX.LIB / DCLIPX.DLL:<br><br>For complete documentation on how to use these functions, see the ACE.HLP file available from Extended Systems. <pre> AdsApplicationExit AdsBeginTransaction AdsCacheOpenTables AdsCheckExistence AdsClearDefault AdsClearProgressCallback AdsCommitTransaction AdsConnect AdsConnect26 AdsDisconnect AdsFailedTransactionRecovery AdsFindConnection AdsFindConnection25 AdsGetAllTables AdsGetCollationLang AdsGetConnectionType AdsGetDateFormat AdsGetDecimals AdsGetDefault AdsGetDeleted AdsGetEpoch AdsGetErrorString AdsGetExact AdsGetExact22 AdsGetLastError AdsGetNumOpenTables AdsGetSearchPath AdsGetServerName AdsGetServerTime AdsGetVersion AdsInTransaction AdsIsServerLoaded AdsNullTerminateStrings AdsRegisterProgressCallback AdsRollbackTransaction AdsSetCollationLang AdsSetDateFormat AdsSetDecimals AdsSetDefault AdsSetEpoch AdsSetExact AdsSetExact22 AdsSetSearchPath AdsSetServerType AdsShowDeleted AdsShowError AdsThreadExit AdsWriteAllRecords </pre>

Files:

_DCADS.PRG, DCLIPX.DLL

See Also:

   FUNCTIONS_AX


FUNCTIONS_ADS_DATA

Ads_*() Data Manipulation Functions (Advantage Server)

The following list of Ads*() data manipulation functions are supported in DCLIPX.LIB / DCLIPX.DLL:<br><br>For complete documentation on how to use these functions, see the ACE.HLP file available from Extended Systems. <pre> AdsAppendRecord AdsBinaryToFile AdsBuildRawKey AdsDeleteRecord AdsFileToBinary AdsGetBinary AdsGetBinaryLength AdsGetDate AdsGetDouble AdsGetField AdsGetJulian AdsGetLogical AdsGetLong AdsGetMemoDataType AdsGetMemoLength AdsGetMilliseconds AdsGetRecord AdsGetShort AdsGetString AdsGetTime AdsImageToClipboard AdsInitRawKey AdsIsEmpty AdsRecallRecord AdsSetBinary AdsSetDate AdsSetDouble AdsSetEmpty AdsSetField AdsSetJulian AdsSetLogical AdsSetLong AdsSetMilliseconds AdsSetRecord AdsSetShort AdsSetString AdsSetTime AdsSetTimeStamp AdsWriteRecord </pre>

Files:

_DCADS.PRG, DCLIPX.DLL

See Also:

   FUNCTIONS_AX
   FUNCTIONS_ADS_DRIVER
   FUNCTIONS_ADS_TABLE


FUNCTIONS_ADS_SQL

Ads_*() SQL Functions (Advantage Server)

The following list of Ads*() SQL functions are supported in DCLIPX.LIB / DCLIPX.DLL:<br><br>For complete documentation on how to use these functions, see the ACE.HLP file available from Extended Systems. <pre> AdsCacheOpenCursors AdsClearSQLAbortFunc AdsClearSQLParams AdsCloseSQLStatement AdsCreateSQLStatement AdsExecuteSQL AdsExecuteSQLDirect AdsPrepareSQL AdsRegisterSQLAbortFunc AdsStmtClearTablePasswords AdsStmtConstrainUpdates AdsStmtDisableEncryption AdsStmtEnableEncryption AdsStmtSetTableCharType AdsStmtSetTableLockType AdsStmtSetTablePassword AdsStmtSetTableReadOnly AdsStmtSetTableRights AdsStmtSetTableType </pre>

Files:

_DCADS.PRG, DCLIPX.DLL

See Also:

   FUNCTIONS_AX
   FUNCTIONS_ADS_DRIVER
   FUNCTIONS_ADS_TABLE


FUNCTIONS_ADS_MG

Ads_*() Management Functions (Advantage Server)

The following list of Ads*() SQL functions are NOT supported in DCLIPX.LIB / DCLIPX.DLL because they are included in the ADSMG.LIB / ADSMG.DLL files distributed with the ADSDBE from Alaska Software:<br><br>For complete documentation on how to use these functions, see the ACE.HLP file available from Extended Systems. <pre> AdsMgConnect AdsMgDisconnect AdsMgGetActivityInfo AdsMgGetCommStats AdsMgGetConfigInfo AdsMgGetInstallInfo AdsMgGetLockOwner AdsMgGetLocks AdsMgGetOpenIndexes AdsMgGetOpenTables AdsMgGetServerType AdsMgGetUserNames AdsMgGetWorkerThreadActivity AdsMgKillUser AdsMgResetCommStats </pre><br><br>

Files:

_DCADS.PRG, DCLIPX.DLL

See Also:

   FUNCTIONS_AX
   FUNCTIONS_ADS_DRIVER
   FUNCTIONS_ADS_TABLE


DCCOLOR.INI

The color configuration file

DCCOLOR.INI is a color configuration file that is used to store the different color "palettes" for dCLIP high-level functions and menus. A default set of colors (one palette only) is built-in to dCLIP. This color set is named the "Standard Color Set" and may be modified by using the COLOR SETUP command or DC_CLRSETUP() function. Once the color configuration has been changed, the new configuration is saved in DCCOLOR.INI.<br><br> The user may create as many color "palettes" as desired to meet individual needs. For example, if you use wish to establish a mulitiple-window browse with a different color scheme for each window, you will need to create a new color set. This is accomplished in the COLOR SETUP menu or by using the DC_COLORADD() function.<br><br> Selecting a color set is accomplished via the BROWSE / EDITING menus, COLOR SETUP menu, or DC_COLORSEL() function.<br><br> DCCOLOR.INI is a Windows-style initialization file that stores the values in the PUBLIC "DCCOLOR" color array and is used to restore the array at startup time. If this file does not exist it will be created.<br><br>

Files:

DCCOLOR.INI


HEADER SYMBOLS

Definition of dCLIP color manifest symbols/constants

// dCLIP Color Manifest Symbols<br><br> The below manifest "symbols" can be used in your source code to set a system color. These symbols are used with the DC_COLOR() or SETCOLOR() function as follows:<br><br> -- Examples --<br><br> #include "dccolor.ch"<br><br> DC_COLOR( cC_POPMENF ) // set color of pulldown menu frames<br><br> Manifest Symbol Array element Description ------------ ---------------------- ----------------------------<br><br> cC_DOTPROMPT dCCOLOR[dCCOLOR[1]+1,1] Main dot-prompt cC_BRMENUF dCCOLOR[dCCOLOR[1]+1,2] Browse menus frame cC_BRMENUD dCCOLOR[dCCOLOR[1]+1,3] Browse menus data cC_BRMENUH dCCOLOR[dCCOLOR[1]+1,4] Browse menus header cC_BRMENUB dCCOLOR[dCCOLOR[1]+1,5] Browse menus menu bar cC_BRMENUS dCCOLOR[dCCOLOR[1]+1,6] Browse menus select bar cC_POPMENF dCCOLOR[dCCOLOR[1]+1,7] Popup / pulldown menu frames cC_POPMENI dCCOLOR[dCCOLOR[1]+1,8] Popup / pulldown menu items cC_POPMENS dCCOLOR[dCCOLOR[1]+1,9] Popup / pulldown menu select cC_MEMOBOX dCCOLOR[dCCOLOR[1]+1,10] All memos box cC_MEMOTXT dCCOLOR[dCCOLOR[1]+1,11] All memos contents cC_EXPBOXF dCCOLOR[dCCOLOR[1]+1,12] Exploding boxes frame cC_EXPBOXC dCCOLOR[dCCOLOR[1]+1,13] Exploding boxes contents cC_DBUGGER dCCOLOR[dCCOLOR[1]+1,14] DBUGGER main screen cC_WARNBOX dCCOLOR[dCCOLOR[1]+1,15] Warning boxes frame cC_WARNTXT dCCOLOR[dCCOLOR[1]+1,16] Warning boxes contents cC_DBUGBOX dCCOLOR[dCCOLOR[1]+1,17] Debug boxes frames cC_DBUGTXT dCCOLOR[dCCOLOR[1]+1,18] Debug boxes contents cC_DBUGBAR dCCOLOR[dCCOLOR[1]+1,19] Debug boxes select bar cC_SPECIAL dCCOLOR[dCCOLOR[1]+1,20] Special codes cC_SAY dCCOLOR[dCCOLOR[1]+1,21] SAYs cC_PENDGET dCCOLOR[dCCOLOR[1]+1,22] Pending GETs cC_CURRGET dCCOLOR[dCCOLOR[1]+1,23] Current GET cC_STAT1 dCCOLOR[dCCOLOR[1]+1,24] Dot-prompt status line / lines cC_STAT2 dCCOLOR[dCCOLOR[1]+1,25] Dot-prompt status line / data cC_POPGRAY dCCOLOR[dCCOLOR[1]+1,26] Pop-up menus gray items<br><br> lC_BLINKBIT dCCOLOR[dCCOLOR[1]+1,34] Blink-bit or High Intensity cC_SETNAME dCCOLOR[dCCOLOR[1]+1,35] Name of this color set<br><br> nC_COLORNAME 35 Numeric value of cC_SETNAME nC_COLORPAL dCCOLOR[1] Selected color palette<br><br> // dCLIP Color Manifest Constants<br><br> The below manifest "constants" can be used in your source code to set a system color. These constants are used with the DC_COLOR() function as follows:<br><br> DC_COLOR( nC_MEMOBOX ) // set color to memo box color<br><br> Manifest Constant Value Description ---------- ----- -------------------------------------- nC_DOTPROMPT 1 Main dot-prompt nC_BRMENUF 2 Browse menus frame nC_BRMENUD 3 Browse menus data nC_BRMENUH 4 Browse menus header nC_BRMENUB 5 Browse menus menu bar nC_BRMENUS 6 Browse menus select bar nC_POPMENF 7 Popup / pulldown menu frames nC_POPMENI 8 Popup / pulldown menu items nC_POPMENS 9 Popup / pulldown menu select bars nC_MEMOBOX 10 All memos box nC_MEMOTXT 11 All memos contents nC_EXPBOXF 12 Exploding boxes frame nC_EXPBOXC 13 Exploding boxes contents nC_DBUGGER 14 DBUGGER main screen nC_WARNBOX 15 Warning boxes frame nC_WARNTXT 16 Warning boxes contents nC_DBUGBOX 17 Debug boxes frames nC_DBUGTXT 18 Debug boxes contents nC_DBUGBAR 19 Debug boxes select bar nC_SPECIAL 20 Special codes nC_SAY 21 SAYs nC_PENDGET 22 Pending GETs nC_CURRGET 23 Current GET nC_STAT1 24 Dot-prompt status line / lines nC_STAT2 25 Dot-prompt status line / data nC_BLINKBIT 34 Blink-bit or High Intensity nC_SETNAME 35 Name of this color set nC_POPGRAY 36 Name of this color set nC_SAYGETS 100 Standard foreground/background for SAYS..GETS

Files:

DCCOLOR.CH